Changeset 27780 in project


Ignore:
Timestamp:
11/05/12 22:15:34 (8 years ago)
Author:
sjamaan
Message:

Add initial documentation for spiffy-cgi-handlers and spiffy-dynamic-handlers. Update spiffy documentation by pointing to these egg pages.

Location:
wiki/eggref/4
Files:
2 added
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/spiffy

    r27767 r27780  
    404404             (,(glob->regexp "*.domain.com") .
    405405                ,(lambda (continue)
     406                   ;; Requires the spiffy-cgi-handlers egg...
    406407                   (parameterize ((file-extension-handlers
    407408                                    `(("php" . ,(cgi-handler* "/usr/pkg/libexec/cgi-bin/php"))))
     
    584585==== ssp-handler
    585586
    586 '''Note:''' ssp-handler is ''deprecated'' for two reasons.
    587 
    588 First, it's ugly in that it is presentation-first (code needs to be
    589 "escaped" into) and thereby encourages mixing code and presentation.
    590 
    591 Second, it's a potential security hazard as it requires you to put code
    592 in your documentroot which often needs to be writable in order to store
    593 user-uploaded assets.  Protecting only those directories is tricky and
    594 easily forgotten.
    595 
    596 This '''will''' be removed in a future release of Spiffy.  It might get
    597 moved into a separate egg if enough people are still relying on this.
    598 
    599 SSP, or Scheme Server Pages, are a way to embed Scheme in HTML
    600 pages.  Files with an extension of {{.ssp}} are handled specifically,
    601 by replacing occurrences of certain reserved tags with Scheme code.
    602 There are two possible forms, either the long version, where all
    603 output is redirected to the HTTP response port, or the short, where
    604 the result of the embedded expression is displayed in the response.
    605 The tags default to {{<?scheme}} and {{<?}}, see Configuration for how
    606 to change them.
    607 
    608 <enscript highlight=scheme>
    609    <html><body>
    610    <ol><?scheme (for-each (lambda (i) (printf "<li>~S~%" i)) (iota 5))?></ol>
    611    <br />
    612    <b><?(call-with-values (lambda () (user-information (current-user-id))) (lambda (name . _) name))?><b>
    613    </body></html>
    614 </enscript>
    615 
    616 would generate for example something like this:
    617 
    618      1. 0
    619      2. 1
    620      3. 2
    621      4. 3
    622      5. 4
    623 
    624   (felix x 500 100 /home/felix /bin/bash)
    625 
    626 When a {{.ssp}} file is loaded the first time, or when it has been
    627 modified, then a translation takes place that generates a loadable
    628 Scheme source file (with the extension {{.sspx}}, in the same
    629 directory as the original file) from the original data, so in the
    630 above example something like this would be generated:
    631 
    632 <enscript highlight=scheme>
    633   (let ()
    634     (display "<html><body>\n<ol>")
    635     (for-each (lambda (i) (printf "<li>~S~%" i)) (iota 5))
    636     (display "</ol>\n<br />\n<b>")
    637     (display (call-with-values (lambda () (user-information (current-user-id))) (lambda (name . _) name)))
    638     (display "<b>\n</body></html>\n") )
    639 </enscript>
    640 
    641 Note that the body is evaluated in a {{(let () ...)}} form.
    642 
    643 Note: each request runs in a separate thread, so code in {{.ssp}}
    644 pages should take care when using global variables.
    645 
    646 ===== Configuration
    647 
    648 The SSP handler can be configured with the following options:
    649 
    650 <parameter>(ssp-short-open-tag [tag-regexp])</parameter>
    651 
    652 The opening tag for short fragments. Default: {{<?}}
    653 
    654 <parameter>(ssp-long-open-tag [tag-regexp])</parameter>
    655 
    656 The opening tag for long fragments. Default: {{<?scheme}}
    657 
    658 <parameter>(ssp-close-tag [tag-regexp])</parameter>
    659 
    660 The closing tag for Scheme fragments in {{.ssp}} files. Default: {{?>}}
    661 
    662 <parameter>(ssp-eval-environment [environment])</parameter>
    663 
    664 The environment passed to {{eval}} when evaluating Scheme code inside
    665 {{.ssp}}-pages.  Default: {{interaction-environment}}
    666 
    667 <parameter>(ssp-cache-dir [directory-name])</parameter>
    668 
    669 The directory under which to store cached .ssp files (these end in .sspx
    670 and are pure Scheme files).  Useful if you want to block write access to
    671 the webserver under your docroot.  Default: {{"."}}
    672 
    673 If it's a relative path, it is relative to {{root-path}}, if absolute
    674 it's taken to be relative to the filesystem root.  A directory structure
    675 similar to the docroot will be created underneath this path, so for
    676 example if the file {{/foo/bar/qux.ssp}} exists, and the cache dir is
    677 set to {{/cache}}, it will create the file {{/cache/foo/bar/qux.sspx}}.
    678 
    679 ===== Runtime information
    680 
    681 For the duration of evaluating a SSP page, the following parameters
    682 will have a value assigned to them:
    683 
    684 <parameter>(current-workdir [path])</parameter>
    685 
    686 During execution, the current working directory of the SSP handler.
    687 Any of the "include" procedures (ssp-include, ssp-stringize) will
    688 interpret their file arguments to be relative to this directory.
    689 
    690 <parameter>(ssp-exit-handler [handler])</parameter>
    691 
    692 During execution of an ssp page, {{ssp-exit-handler}} is bound to a
    693 procedure that will finish the current page, ignoring any further
    694 content or code.
    695 
    696 ===== Procedures
    697 
    698 The ssp-handler module adds the following procedures to the environment:
    699 
    700 <procedure>(ssp-handler filename)</procedure>
    701 
    702 The handler itself, which should be used in the {{file-extension-handlers}}
    703 parameter list.
    704 
    705 <procedure>(ssp-include filename)</procedure>
    706 
    707 Translates the file {{filename}} into Scheme by replacing {{<?scheme ... ?>}}
    708 and {{<? ... ?>}} sequences (if needed) and writes the translated contents
    709 to the current output-port.
    710 
    711 <procedure>(ssp-stringize FILENAME)</procedure>
    712 
    713 Similar to {{ssp-include}}, but instead of writing the translated
    714 text, the text is returned as a string.
     587This was moved to the [[spiffy-dynamic-handlers]] egg.
    715588
    716589==== web-scheme-handler
    717590
    718 '''Note:''' This extension is deprecated for one of the reasons
    719 the ssp-handler is deprecated; it requires you to put code in
    720 your document root, which often needs to be (partially) writable by
    721 the webserver, thereby promoting insecure practices.  Please drop
    722 me a line if you're using it so I know whether it's worth putting
    723 into an egg.
    724 
    725 Another way of executing Scheme code to produce content are {{.ws}}
    726 files: these should contain a Scheme expression that is expected to
    727 evaluate to a string which will be directly written as the response to
    728 the current request. This facility is intended for Scheme code that
    729 uses the [[web-scheme]] extension.
    730 
    731 You can use the {{web-scheme-handler}} for any Scheme file which
    732 returns HTML as a string or which has a side-effect of outputting the
    733 HTML. If it's the latter, make sure the final statement in your file
    734 does not return a string or it will be appended to the output (just
    735 like in the {{csi}} REPL).
    736 
    737 '''Tip''' This handler type is perfect not only for web-scheme but
    738 also for when you're using {{SRV:send-reply}} with SXML or for example a
    739 wiki-to-string translator.
    740 
    741 Note: each request runs in a separate thread, so code in {{.ws}} pages
    742 should take care when using global variables.
    743 
    744 Note: web-scheme-handler is a separate extension and must be imported
    745 as such.
    746 
    747 <enscript highlight=scheme>
    748 (require-extension web-scheme-handler)
    749 </enscript>
    750 
    751 ===== Configuration
    752 
    753 The Web-scheme handler can be configured with the following options:
    754 
    755 <parameter>(web-scheme-eval-environment [environment])</parameter>
    756 
    757 The environment passed to {{eval}} when evaluating Scheme code inside
    758 {{.ws}}-pages.  Default: {{interaction-environment}}
    759 
    760 ===== Procedures
    761 
    762 The Web-scheme handler adds only one procedure to the environment:
    763 
    764 <procedure>(web-scheme-handler filename)</procedure>
    765 
    766 The handler itself, which should be used in the {{file-extension-handlers}}
    767 parameter list.
    768 
     591This was moved to the [[spiffy-dynamic-handlers]] egg.
    769592
    770593==== cgi-handler
    771594
    772 Spiffy supports [[http://www.ietf.org/rfc/rfc3875|CGI/1.1 as specified by RFC 3875]].
    773 
    774 All request headers will be passed as environment variables to the CGI
    775 program, prefixed with {{"HTTP_"}}, and converted to uppercase, with
    776 hyphens ("-") replaced by an underscore ("_"). The CGI program will
    777 receive the request body in unparsed form from stdin and should write
    778 a complete HTTP response to stdout.  Any headers that are missing but
    779 required for HTTP will be added by Spiffy.  For more info on how a CGI
    780 script is called, consult the spec.
    781 
    782 The {{AUTH_TYPE}} and {{REMOTE_USER}} environment variables are
    783 currently not set during invocation of CGI subprocesses.
    784 The {{REMOTE_IDENT}} environment variable is not and never will be supported.
    785 
    786 ===== Configuration
    787 
    788 CGI handler can be configured with the following parameters:
    789 
    790 <procedure>(cgi-default-environment [env-alist])</procedure>
    791 
    792 The environment variables that should be in the default environnment
    793 of every CGI program.  Variables like {{SCRIPT_NAME}} will be added
    794 dynamically to the end of this alist.
    795 
    796 Default:
    797 
    798 <enscript highlight=scheme>
    799 (("GATEWAY_INTERFACE" . "CGI/1.1"))
    800 </enscript>
    801 
    802 ===== Procedures
    803 
    804 CGI-handler adds two procedures to the environment:
    805 
    806 <procedure>(cgi-handler filename [interpreter])</procedure>
    807 
    808 The cgi handler simply calls CGI scripts. It is assumed the
    809 requested file is executable if no interpreter is given.
    810 (If used as a regular handler, it will only receive the
    811 filename).  If the filename is a relative path, it is assumed
    812 to be relative to {{(root-path)}}.  It's safer to store your
    813 scripts outside the docroot, though!
    814 
    815 <procedure>(cgi-handler* [interpreter])</procedure>
    816 
    817 The {{cgi-handler*}} procedure is usually more useful.  It allows you
    818 to define an interpreter to use for files and returns a new handler.
    819 See the example above for {{file-extension-handlers}}.
    820 
     595This was moved to the [[spiffy-cgi-handlers]] egg.
    821596
    822597==== simple-directory-handler
     
    887662=== Changelog
    888663
    889 * trunk Work around race conditions in {{simple-directory-handler}} related to deleted files or self-referential symlinks (reported by [[/users/mario-domenech-goulart|Mario]]). Move deprecated dynamic content handlers into separate [[spiffy-dynamic-handlers]] egg (TODO: Move documentation into separate page, add egg to egg-locations and tag spiffy)
     664* 4.16 Work around race conditions in {{simple-directory-handler}} related to deleted files or self-referential symlinks (reported by [[/users/mario-domenech-goulart|Mario]]). Move deprecated dynamic content handlers into separate [[spiffy-dynamic-handlers]] egg. Move cgi handler into separate [[spiffy-cgi-handlers]] egg.
    890665* 4.15 Disallow non-{{GET}}/{{HEAD}} requests for normal files in {{handle-file}}.  Remove dependencies on [[/eggref/4/matchable|matchable]] and [[/eggref/4/regex|regex]] eggs.  Allow request-uri overrides in user lambdas to affect the default handler (Thanks to [[/users/mario-domenech-goulart|Mario]]).
    891666* 4.14 Fix ssp-handler's pathname construction so it doesn't error on files in the rootdirectory.  Fix incompatibility with version 1.6.1 of the OpenSSL egg [Thanks to [[/users/mario-domenech-goulart|Mario]] and [[/users/thomas-chust|Thomas]].]
Note: See TracChangeset for help on using the changeset viewer.