http-server.h revision 582b93659812592a27babdb65c6cb4c37042ab00
#ifndef HTTP_SERVER_H
#define HTTP_SERVER_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;
struct http_server_settings {
const char *rawlog_dir;
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. */
bool debug;
};
struct http_server_stats {
unsigned int request_count, response_count;
};
struct http_server_tunnel {
};
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. 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,
};
typedef void (*http_server_tunnel_callback_t)(void *context,
const struct http_server_tunnel *tunnel);
/* shut down the server; accept no new requests and drop connections once
they become idle */
struct http_server_connection *
/* Returns FALSE if unrefing destroyed the connection entirely */
const char *reason);
const struct http_server_stats *
const struct http_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);
/* 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. */
/* Send an authentication failure response to 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 to 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.
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);
/* Reference a server request */
/* Unreference a server request. Returns TRUE if there are still more
references, FALSE if not. */
/* Start creating the response for the request. This function can be called
only once for each request. */
struct http_server_response *
/* Change the response code and text, cannot be used after submission */
struct ostream *
bool blocking);
/* get some information about response */
struct http_server_response *resp,
const struct http_auth_challenge *chlng);
/* Submit response and close the connection. */
/* submits response and blocks until provided payload is sent. Multiple calls
are allowed; 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. */
/* 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 */
#endif