chickadee » mongrel2

mongrel2

Description

This egg provides an API for writing Mongrel2 handlers. Mongrel2 strives to be an application, language, and network architecture agnostic web server. The server itself is written in C and is required to actually put handlers created with this egg to use. Mongrel2 communicates with its handlers via ZeroMQ.

The API comes in two flavors: mongrel2-lolevel which is modeled after the Python example handler code of the distribution (see examples/python in the Mongrel2 tarball) and mongrel2 which is built on top of that and modeled after spiffy's API.

Author

Moritz Heidkamp

Caveat

This API is very experimental and may change significantly in the near future.

Documentation

The following assumes that you are familiar with ZeroMQ as well as Mongrel2's architecture. If you aren't yet, go read the ZeroMQ guide and/or the Mongrel2 Manual.

mongrel2-lolevel

(connect-handler id response-endpoint request-endpoint #!optional request-id) procedure

Creates and connects two zmq sockets for communicating with a Mongrel2 server. The id is used as the PUB socket's identity and request-endpoint is a zmq endpoint string for that socket to connect to. Correspondingly, request-endpoint is the zmq endpoint string for the PULL socket to connect to. Optionally, an identity for that socket can be given as request-id. The return value is an opaque connection record which is further referred to as a connection.

(receive-request connection) procedure

Receives a request from connection. This will block the current thread until a request is available. Requests are returned in the form of a record which can be inspected with several procedures also available in this module.

(request-disconnect? request) procedure

Checks whether the given request signifies a disconnect event.

(request-sender request) procedure

Returns the given request's sender UUID as a string.

(request-path request) procedure

Returns the given request's URI path as a string.

(request-headers request) procedure

Returns the given request's headers as an alist with the keys being symbols.

(request-header name request) procedure

Return the value of request's header name which must be a symbol. If there no header of that name is found, #f is returned.

(request-method request) procedure

Returns the given request's method as a symbol, e.g. JSON or GET.

(request-body request) procedure

Returns the given request's body as a string.

(request-data request) procedure

Returns the given request's body in a structured format. This depends on the request's method. Currently it will only handle requests of the type JSON and return the body's contents parsed by the json egg.

(request-id request) procedure

Returns the given request's listener id as a string.

(request-type) procedure

Returns the given request's type as a symbol. This is either json, xml or http.

(request-uri) procedure

Returns the given request's URI as a uri-common record.

(send-response request response) procedure

Sends a response string for the given request.

(send-http-response request #!key code reason body headers response) procedure

Sends an HTTP response for the given request. The arguments are exactly the same as those of spiffy's send-response with the addition of the keyword argument response which can be used to pass in an intarweb response record to be used as a basis (default is an empty response record).

mongrel2

(handler-response-id [id]) parameter

The response socket's identity string.

(handler-response-endpoint [endpoint]) parameter

The response socket's endpoint string.

(handler-request-id [id]) parameter

The request socket's identity string.

(handler-request-endpoint [endpoint]) parameter

The request socket's endpoint string.

(current-request [request]) parameter

The current Mongrel2 request record (see the mongrel2-lolevel module for available accessors).

(current-http-request [http-request]) parameter

If the current-request's request-type is http, this parameter holds a corresponding intarweb request record. Otherwise it will be #f.

(current-http-response [http-response]) parameter

If the current-request's request-type is http, this parameter holds an intarweb response record which can be used to build up a response. Otherwise it will be #f.

(handler-start [handler]) procedure

Starts the handler mainloop. handler is a thunk which is called for each incoming request with the above paramters set accordingly. It is expected to send a response to current-request. See send-response and send-http-response on how to do that.

(send-response body) procedure

Sends the string body as the response for current-request.

(send-http-response #!key code reason body headers) procedure

Sends a HTTP response for current-request. This procedure works exactly like spiffy's send-response.

Examples

mongrel2-lolevel

(use mongrel2-lolevel)

(define conn (connect-handler "6cafb469-3b40-40c1-a50a-ede619ce3d16"
                              "tcp://127.0.0.1:1234"
                              "tcp://127.0.0.1:1235"
                              "55752929-b6c0-4015-9e9e-17c765c90a12"))

(let loop ()
  
  (print "WAITING FOR REQUEST")

  (let ((req (receive-request conn)))

    (if (request-disconnect? req)
        (print "DISCONNECT")
        (send-http-response req 
                            body: (format "\nSENDER: ~A\nIDENT: ~A\nPATH: ~A\nHEADERS: ~S\nBODY: ~A"
                                          (request-sender req)
                                          (request-id req)
                                          (request-path req)
                                          (request-headers req) 
                                          (request-body req))
                            headers: '((content-type text/plain)))))
  
  (loop))

mongrel2

(use mongrel2 uri-common (prefix intarweb http-))
                              
(handler-response-id "6cafb469-3b40-40c1-a50a-ede619ce3d16")
(handler-response-endpoint "tcp://127.0.0.1:1234")
(handler-request-id "55752929-b6c0-4015-9e9e-17c765c90a12")
(handler-request-endpoint "tcp://127.0.0.1:1235")

(handler-start (lambda ()
                 (let ((uri (uri->string (http-request-uri (current-http-request)))))
                   (send-http-response body: (format "thank you for requesting ~A" uri)))))

Contents »