Spiffy-dynamic-handlers

  1. Spiffy-dynamic-handlers
    1. Description
    2. Author
    3. Requirements
    4. Handlers
      1. ssp-handler
        1. Configuration
        2. Runtime information
        3. Procedures
      2. web-scheme-handler
        1. Configuration
        2. Procedures
    5. Changelog
    6. License

Description

Deprecated Spiffy handlers for dynamic file-based website scripting.

These handlers are deprecated for two reasons, so please reconsider before relying on them:

First (this goes for both handlers), it's a potential security hazard as it requires you to put code in your documentroot which often needs to be writable in order to store user-uploaded assets. Protecting only those directories is tricky and easily forgotten.

Second, SSP pages are a very ugly style in that it is presentation-first (code needs to be "escaped" into) and thereby encourages mixing code and presentation.

At some point these handlers will be completely dropped and no longer supported.

Author

Felix Winkelmann. Currently maintained by Peter Bex.

Requirements

Requires the spiffy and intarweb extensions.

Handlers

These two handlers (both in a module of the same name) are supplied by the egg.

ssp-handler

SSP, or Scheme Server Pages, are a way to embed Scheme in HTML pages. Files with an extension of .ssp are handled specifically, by replacing occurrences of certain reserved tags with Scheme code. There are two possible forms, either the long version, where all output is redirected to the HTTP response port, or the short, where the result of the embedded expression is displayed in the response. The tags default to <?scheme and <?, see Configuration for how to change them.

Here's an example:

   <html><body>
   <ol><?scheme (for-each (lambda (i) (printf "<li>~S~%" i)) (iota 5))?></ol>
   <br />
   <b><?(call-with-values (lambda () (user-information (current-user-id))) (lambda (name . _) name))?><b>
   </body></html>

would generate for example something like this:

    1. 0
    2. 1
    3. 2
    4. 3
    5. 4 
 (felix x 500 100 /home/felix /bin/bash)

When a .ssp file is loaded the first time, or when it has been modified, then a translation takes place that generates a loadable Scheme source file (with the extension .sspx, in the same directory as the original file) from the original data, so in the above example something like this would be generated:

  (let ()
    (display "<html><body>\n<ol>")
    (for-each (lambda (i) (printf "<li>~S~%" i)) (iota 5))
    (display "</ol>\n<br />\n<b>")
    (display (call-with-values (lambda () (user-information (current-user-id))) (lambda (name . _) name)))
    (display "<b>\n</body></html>\n") )

Note that the body is evaluated in a (let () ...) form.

Note: each request runs in a separate thread, so code in .ssp pages should take care when using global variables.

Configuration

The SSP handler can be configured with the following options:

[parameter] (ssp-short-open-tag [tag-regexp])

The opening tag for short fragments. Default: <?

[parameter] (ssp-long-open-tag [tag-regexp])

The opening tag for long fragments. Default: <?scheme

[parameter] (ssp-close-tag [tag-regexp])

The closing tag for Scheme fragments in .ssp files. Default: ?>

[parameter] (ssp-eval-environment [environment])

The environment passed to eval when evaluating Scheme code inside .ssp-pages. Default: interaction-environment

[parameter] (ssp-cache-dir [directory-name])

The directory under which to store cached .ssp files (these end in .sspx and are pure Scheme files). Useful if you want to block write access to the webserver under your docroot. Default: "."

If it's a relative path, it is relative to root-path, if absolute it's taken to be relative to the filesystem root. A directory structure similar to the docroot will be created underneath this path, so for example if the file /foo/bar/qux.ssp exists, and the cache dir is set to /cache, it will create the file /cache/foo/bar/qux.sspx.

Runtime information

For the duration of evaluating a SSP page, the following parameters will have a value assigned to them:

[parameter] (current-workdir [path])

During execution, the current working directory of the SSP handler. Any of the "include" procedures (ssp-include, ssp-stringize) will interpret their file arguments to be relative to this directory.

[parameter] (ssp-exit-handler [handler])

During execution of an ssp page, ssp-exit-handler is bound to a procedure that will finish the current page, ignoring any further content or code.

Procedures

The ssp-handler module adds the following procedures to the environment:

[procedure] (ssp-handler filename)

The handler itself, which should be used in the file-extension-handlers parameter list.

[procedure] (ssp-include filename)

Translates the file filename into Scheme by replacing <?scheme ... ?> and <? ... ?> sequences (if needed) and writes the translated contents to the current output-port.

[procedure] (ssp-stringize FILENAME)

Similar to ssp-include, but instead of writing the translated text, the text is returned as a string.

web-scheme-handler

Another way of executing Scheme code to produce content are .ws files: these should contain a Scheme expression that is expected to evaluate to a string which will be directly written as the response to the current request. This facility is intended for Scheme code that uses the web-scheme extension.

You can use the web-scheme-handler for any Scheme file which returns HTML as a string or which has a side-effect of outputting the HTML. If it's the latter, make sure the final statement in your file does not return a string or it will be appended to the output (just like in the csi REPL).

Tip This handler type is perfect not only for web-scheme but also for when you're using SRV:send-reply with SXML or for example a wiki-to-string translator.

Note: each request runs in a separate thread, so code in .ws pages should take care when using global variables.

Note: web-scheme-handler is a separate extension and must be imported as such.

(require-extension web-scheme-handler)
Configuration

The Web-scheme handler can be configured with the following options:

[parameter] (web-scheme-eval-environment [environment])

The environment passed to eval when evaluating Scheme code inside .ws-pages. Default: interaction-environment

Procedures

The Web-scheme handler adds only one procedure to the environment:

[procedure] (web-scheme-handler filename)

The handler itself, which should be used in the file-extension-handlers parameter list.

Changelog

0.1 Moved deprecated ssp-handler and web-scheme-handler from spiffy to their own egg. Finally wrote some regression tests.

License

 Copyright (c) 2007-2012, Peter Bex
 Copyright (c) 2000-2005, Felix L. Winkelmann
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 
 Neither the name of the author nor the names of its contributors may
 be used to endorse or promote products derived from this software
 without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.