http-server.h revision fab1c263d60ee6a08f162af2146ff0ccf6b36061
#ifndef HTTP_SERVER_H
#define HTTP_SERVER_H
#include "http-common.h"
#include "http-auth.h"
#include "http-request.h"
struct istream;
struct ostream;
struct http_request;
struct http_server;
struct http_server_request;
struct http_server_response;
/*
* Server settings
*/
struct http_server_settings {
const char *rawlog_dir;
/* The maximum time in milliseconds a client is allowed to be idle before
it is disconnected. */
unsigned int max_client_idle_time_msecs;
/* Maximum number of pipelined requests per connection (default = 1) */
unsigned int max_pipelined_requests;
/* Request limits */
struct http_request_limits request_limits;
Configuring this is mainly useful for the test suite. The kernel
defaults are used when these settings are 0. */
/* Enable logging debug messages */
bool debug;
};
/*
* Response
*/
/* Connection data for an established HTTP tunnel */
struct http_server_tunnel {
};
typedef void (*http_server_tunnel_callback_t)(void *context,
const struct http_server_tunnel *tunnel);
/* Start creating the response for the request. This function can be called
only once for each request. */
struct http_server_response *
/* Add a custom header to the response. This can override headers that are
otherwise created implicitly. */
/* Change the response code and text, cannot be used after submission */
/* Set the value of the "Date" header for the response using a time_t value.
Use this instead of setting it directly using
http_server_response_add_header() */
/* Assign an input stream for the outgoing payload of this response. The input
stream is read asynchronously while the response is sent to the client. */
/* Assign payload data to the response. The data is copied to the request pool.
If your data is already durably allocated during the existence of the
response, you should consider using http_server_response_set_payload() with
a data input stream instead. This will avoid copying the data unnecessarily.
*/
/* Obtain an output stream for the response payload. This is an alternative to
using http_server_response_set_payload(). Currently, this can only return a
blocking output stream. The request is submitted implicitly once the output
stream is written to. Closing the stream concludes the payload. Destroying
the stream before that aborts the response and closes the connection.
*/
struct ostream *
bool blocking);
/* Get the status code and reason string currently set for this response. */
/* Get the total size of the response when sent over the connection. */
/* Add authentication challenge to the response. */
struct http_server_response *resp,
const struct http_auth_challenge *chlng);
/* Add "Basic" authentication challenge to the response. */
/* Submit the response. It is queued for transmission to the client. */
/* Submit the response and close the connection once it is sent. */
/* Submit the response and turn the connection it is sent across into a tunnel
once it is sent successfully. The callback is called once that happens. */
/* Submits response and blocks until provided payload is sent. Multiple calls
are allowed; payload is sent in chunks this way. Payload transmission is
finished with http_server_response_finish_payload(). If the sending fails,
returns -1 and sets resp=NULL to indicate that the response was freed,
otherwise returns 0 and resp is unchanged.
An often more convenient ostream wrapper API is available as
http_server_response_get_payload_output() with blocking=TRUE.
*/
/* Finish sending the payload. Always frees resp and sets it to NULL.
Returns 0 on success, -1 on error. */
/* Abort response payload transmission prematurely. This closes the associated
connection */
/*
* Request
*/
/* Get the parsed HTTP request information for this request. */
const struct http_request *
/* Reference a server request */
/* Unreference a server request. Returns TRUE if there are still more
references, FALSE if not. */
/* Set flag that determines whether the connection is closed after the
request is handled. */
bool close);
/* Get the pool for this request. */
/* Returns the response created for the request with
http_server_response_create(), or NULL if none. */
struct http_server_response *
/* Returns TRUE if request is finished either because a response was sent
or because the request was aborted. */
/* Return input stream for the request's payload. Optionally, this stream
can be made blocking. Do *NOT* meddle with the FD of the http_request
payload to achieve the same, because protocol violations will result.
*/
struct istream *
bool blocking);
/* Forward the incoming request payload to the provided output stream in the
background. Calls the provided callback once the payload was forwarded
successfully. If forwarding fails, the client is presented with an
appropriate error. If the payload size exceeds max_size, the client will
get a 413 error. Before the callback finishes, the application must either
have added a reference to the request or have submitted a response. */
#define http_server_request_forward_payload(req, \
/* Forward the incoming request payload to the provided buffer in the
background. Behaves identical to http_server_request_forward_payload()
otherwise. */
#define http_server_request_buffer_payload(req, \
/* Handle the incoming request payload by calling the callback each time
more data is available. Payload reading automatically finishes when the
request payload is fully read. Before the final callback finishes, the
application must either have added a reference to the request or have
submitted a response. */
/* Get the authentication credentials provided in this request. Returns 0 if
the Authorization header is absent, returns -1 when that header cannot be
parsed, and returns 1 otherwise */
struct http_auth_credentials *credentials);
and close the connection. */
The text is sent as the response payload, if appropriate. */
/* Send an authentication failure response for the request with given reason.
The provided challenge is set in the WWW-Authenticate header of the
response. */
ATTR_NULL(2);
/* Send a authentication failure response for the request with given reason.
The provided realm is used to construct an Basic challenge in the
WWW-Authenticate header of the response. */
ATTR_NULL(2);
/* Call the specified callback when HTTP request is destroyed. This happens
after one of the following:
a) Response and its payload is fully sent,
b) Response was submitted, but it couldn't be sent due to disconnection or
some other error,
c) http_server_deinit() was called and the request was aborted
Note client disconnection before response is submitted isn't visible to this.
The request payload reading is the responsibility of the caller, which also
must handle the read errors by submitting a failure response. */
void (*callback)(void *),
void *context);
/*
* Connection
*/
/* Connection statistics */
struct http_server_stats {
/* The number of requests received and responses sent */
unsigned int request_count, response_count;
/* Bytes sent and received accross the connection */
};
/* Connection callbacks */
struct http_server_callbacks {
/* Handle the server request. All requests must be sent back a response.
The response is sent either with http_server_request_fail*() or
http_server_response_submit*(). For simple requests you can send the
response back immediately. If you can't do that, you'll need to
reference the request (or the request payload input stream). Then the
code flow usually goes like this:
- http_server_request_set_destroy_callback(destroy_callback)
- http_server_request_ref()
- <do whatever is needed to handle the request>
- http_server_response_create()
- http_server_response_set_payload() can be used especially with
istream-callback to create a large response without temp files.
- http_server_response_submit() triggers the destroy_callback
after it has finished sending the response and its payload.
- In destroy_callback: http_server_request_unref() and any other
necessary cleanup - the request handling is now fully finished.
*/
void (*handle_connect_request)(void *context,
/* Called once the connection is destroyed. */
};
/* Create a HTTP server connection object for the provided fd pair. The
callbacks structure is described above. */
struct http_server_connection *
/* Reference the connection */
/* Dereference the connection. Returns FALSE if unrefing destroyed the
connection entirely */
/* Dereference and close the connection. The provided reason is passed to the
connection_destroy() callback. */
const char *reason);
/* Get the current statistics for this connection */
const struct http_server_stats *
/*
* Server
*/
/* Shut down the server; accept no new requests and drop connections once
they become idle */
/* Switch this server to the current ioloop */
#endif