chickadee » mongrel2

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

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-idprocedure

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 connectionprocedure

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? requestprocedure

Checks whether the given request signifies a disconnect event.

request-sender requestprocedure

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

request-path requestprocedure

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

request-headers requestprocedure

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

request-header name requestprocedure

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 requestprocedure

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

request-body requestprocedure

Returns the given request's body as a string.

request-data requestprocedure

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 requestprocedure

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

request-typeprocedure

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

request-uriprocedure

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

send-response request responseprocedure

Sends a response string for the given request.

send-http-response request #!key code reason body headers responseprocedure

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 #!optional idparameter

The response socket's identity string.

handler-response-endpoint #!optional endpointparameter

The response socket's endpoint string.

handler-request-id #!optional idparameter

The request socket's identity string.

handler-request-endpoint #!optional endpointparameter

The request socket's endpoint string.

current-request #!optional requestparameter

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

current-http-request #!optional http-requestparameter

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 #!optional http-responseparameter

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 #!optional handlerprocedure

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 bodyprocedure

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

send-http-response #!key code reason body headersprocedure

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)))))