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.
This API is very experimental and may change significantly in the near future.
- 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.
Returns the given request's type as a symbol. This is either json, xml or http.
- 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).
- 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
- current-http-response #!optional http-responseparameter
- 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-http-response #!key code reason body headersprocedure
(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))
(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)))))