Cheyenne Developer's Guide

       Author: SOFTINNOV / Nenad Rakocevic
       Date: 12/02/2006
       Version: 1.0
       Comments: cheyenne@softinnov.com

Table of Contents

1. Extension Modules
      1.1. Processing Phases
      1.2. Phase Implementation
      1.3. Module Implementation
2. Builtin modules
      2.1. Mod-Action
            2.1.1. Description
            2.1.2. Phases
            2.1.3. Words
      2.2. Mod-Alias
            2.2.1. Description
            2.2.2. Phases
            2.2.3. Words
      2.3. Mod-Fastcgi
            2.3.1. Description
            2.3.2. Phases
            2.3.3. Words
      2.4. Mod-RSP
            2.4.1. Description
            2.4.2. Phases
            2.4.3. Words
      2.5. Mod-SSI
            2.5.1. Description
            2.5.2. Phases
            2.5.3. Words
      2.6. Mod-Static
            2.6.1. Description
            2.6.2. Phases
            2.6.3. Words
      2.7. Mod-UserDir
            2.7.1. Description
            2.7.2. Phases
            2.7.3. Words



1. Extension Modules

Cheyenne internal architecture is built around a request processing pipeline similar to Apache's one. Each step in this pipeline is called a phase. So each request received by Cheyenne will pass through most of the phases. Cheyenne's HTTPd server just do the protocol related processing for each request and let modules do the useful job. This way of separating the protocol from the data processing and breaking down the processing in several steps, makes the server implementation very flexible and easily customizable.


1.1. Processing Phases

When Cheyenne receives a request, it parses and processes the request by calling the following phases :

# Phase Name Possible usage HTTPd Service Actions
1 - -

  • Request object creation
  • Request first line received and parsed
2 url-translate
  • Early URL or request method changes.
  • <= Phase calling
    3 - -
  • Receiving and parsing HTTP request headers
  • 4 parsed-headers
  • Trigger actions based on received headers.
  • Early HTTP header changes.
  • <= Phase calling
    5 - -
  • Domain name selection
  • Domain configuration loaded in request object
  • 6 url-to-filename
  • Map URL to filesystem.
  • Set a default file if missing.
  • Redirect to another URL.
  • <= Phase calling
    7 - -
  • Receiving POSTed data
  • 8 filter-input
  • Decode the received data. (uncrypt or uncompress)
  • <= Phase calling
    9 access-check
  • File access checking.
  • User authentication management.
  • <= Phase calling
    10 set-mime-type
  • Select the correct MIME type
  • <= Phase calling
    11 make-response
  • Send back the requested file.
  • Build and send a response on-the-fly.
  • Assign an external module to process the request (CGI, RSP,...).
  • <= Phase calling
    12 task-part
  • Process a streamed response from an external module
  • <= Phase calling
    13 task-done
  • Process a correct response from an external module
  • <= Phase calling
    14 task-failed
  • Process an error response from an external module
  • <= Phase calling
    15 filter-output
  • Encode the response data (crypt, compress,...)
  • <= Phase calling
    16 reform-headers
  • Last chance to set/change any HTTP header value
  • <= Phase calling
    17 - -
  • HTTP status line forming
  • HTTP response header forming
  • Response sent to client
  • Close connection (if not pipelining)
  • 18 logging
  • Log some informations on disk
  • <= Phase calling
    19 clean-up
  • Do some cleanup if required
  • <= Phase calling


    1.2. Phase Implementation

    You can do any processing you need in a phase function. You're free to modify the request parameters, send the request in background to be process by an external module, etc...

    Here's a phase prototype function :

    phase: func [svc req conf][
        if declined? [return none]
        ...
        if let-others [return false]
        ...
        true
    ]
    ('declined? and 'let-other would be, in this example, user-defined functions)

    Phase function arguments :

    Argument Type Description
    svc object! Reference to HTTPd context (uniserve/services/httpd)
    req object! Request object. (See below for details)
    conf block! Domain configuration script. (post-processed)

    Request object :

    Words Sub words Type Description
    in headers block! List of [name [word!] value [string!]] header pairs
    status-line binary! First line of the HTTP request
    method word! Request's HTTP method
    url string! Request's extracted URL
    content binary!
    none!
    POST-ed data
    path string!
    none!
    Extracted path of the URL
    target string!
    none!
    Extracted target ressource of the URL
    arg string!
    none!
    Extracted optional arguments of the URL (after # or ?)
    ext string!
    none!
    Extracted extension of the target
    version string!
    none!
    Request's HTTP protocol version
    file string!
    none!
    Complete file name with path for the requested ressource
    translated - (not used)
    out headers block! List of [name [word!] value [string!]] header pairs
    status-line string!
    none!
    Response header first line
    content binary!
    none!
    Response's body
    code integer!
    none!
    Response HTTP status code (1xx-5xx)
    mime lit-pat!
    none!
    Response mime type
    header-sent? logic! True if HTTP header has already been sent (streamed mode)
    state - word! HTTPd service internal state of the request
    handler - word!
    none!
    Handler's name for external processing (task-master related)
    locals - - (not used)
    cfg - block! Reference to configuration data applied to this request
    file-info - object!
    none!
    Ressource file informations returned by REBOL's info? function
    vhost - word! Virtual host name ('default if none)
    deferred? - logic! Flag to set to inform that a request needs an external processing

    Phase return codes :

    Value Description
    None Decline the request and don't do any processing.
    False Request processed. Let other modules process it too (for the current phase).
    True Request processed. Prevent other modules from processing this request (for the current phases).


    1.3. Module Implementation

    Here's a typical phase implementation :

    url-translate: func



    2. Builtin modules


    2.1. Mod-Action


    2.1.1. Description


    2.1.2. Phases


    2.1.3. Words


    2.2. Mod-Alias


    2.2.1. Description


    2.2.2. Phases


    2.2.3. Words


    2.3. Mod-Fastcgi


    2.3.1. Description


    2.3.2. Phases


    2.3.3. Words


    2.4. Mod-RSP


    2.4.1. Description


    2.4.2. Phases


    2.4.3. Words


    2.5. Mod-SSI


    2.5.1. Description


    2.5.2. Phases


    2.5.3. Words


    2.6. Mod-Static


    2.6.1. Description


    2.6.2. Phases


    2.6.3. Words


    2.7. Mod-UserDir


    2.7.1. Description


    2.7.2. Phases


    2.7.3. Words


    Copyright 2004-2006 SOFTINNOV All Rights Reserved.
    Formatted with REBOL Make-Doc 0.9.6.1 on 8-Oct-2006 at 22:26:48