basis/http/server/static/static-docs.factor

   1 ! Copyright (C) 2008 Slava Pestov.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax ;
   4 IN: http.server.static
   5
   6 HELP: <file-responder>
   7 { $values { "root" "a pathname string" } { "hook" { $quotation ( path mime-type -- response ) } } { "responder" file-responder } }
   8 { $description "Creates a file responder which serves content from " { $snippet "path" } " by using the hook to generate a response." } ;
   9
  10 HELP: <static>
  11 { $values
  12     { "root" "a pathname string" }
  13     { "responder" file-responder } }
  14 { $description "Creates a file responder which serves content from " { $snippet "path" } "." } ;
  15
  16 HELP: enable-fhtml
  17 { $values { "responder" file-responder } }
  18 { $description "Enables the responder to serve " { $snippet ".fhtml" } " files by running them." }
  19 { $notes "See " { $link "html.templates.fhtml" } "." }
  20 { $side-effects "responder" } ;
  21
  22 ARTICLE: "http.server.static.extend" "Hooks for dynamic content"
  23 "The static responder can be extended for dynamic content by associating quotations with MIME types in the hashtable stored in the " { $slot "special" } " slot. The quotations have stack effect " { $snippet "( path -- response )" } "."
  24 $nl
  25 "A utility word uses the above feature to enable server-side " { $snippet ".fhtml" } " scripts, allowing a development style much like PHP:"
  26 { $subsections enable-fhtml }
  27 "This feature is also used by " { $vocab-link "http.server.cgi" } " to run " { $snippet ".cgi" } " files."
  28 $nl
  29 "It is also possible to override the hook used when serving static files to the client:"
  30 { $subsections <file-responder> }
  31 "The default just sends the file's contents with the request; " { $vocab-link "xmode.code2html.responder" } " provides an alternate hook which sends a syntax-highlighted version of the file." ;
  32
  33 ARTICLE: "http.server.static" "Serving static content"
  34 "The " { $vocab-link "http.server.static" } " vocabulary implements a responder for serving static files."
  35 { $subsections <static> }
  36 "The static responder does not serve directory listings by default, as a security measure. Directory listings can be enabled by storing a true value in the " { $slot "allow-listings" } " slot."
  37 $nl
  38 "If all you want to do is serve files from a directory, the following phrase does the trick:"
  39 { $code
  40     "USING: namespaces http.server http.server.static ;"
  41     "\"/var/www/mysite.com/\" <static> main-responder set"
  42     "8080 httpd"
  43 }
  44 { $subsections "http.server.static.extend" } ;
  45
  46 ABOUT: "http.server.static"