http-server.h revision 001b7ca6a75e7052511420f9394ed7a7cf008f4a
02c335c23bf5fa225a467c19f2c063fb0dc7b8c3Timo Sirainen#ifndef HTTP_SERVER_H
ba90e657bc68a72ab3b3021e2f4a874fac9965baTimo Sirainen#define HTTP_SERVER_H
46552a931924c2d743f045e95b08c3ce6beda91aTimo Sirainen
ba90e657bc68a72ab3b3021e2f4a874fac9965baTimo Sirainen#include "http-auth.h"
f30577ff7cf29858f1878abe963b4f40a436434fTimo Sirainen#include "http-request.h"
f30577ff7cf29858f1878abe963b4f40a436434fTimo Sirainen
ba90e657bc68a72ab3b3021e2f4a874fac9965baTimo Sirainenstruct istream;
f30577ff7cf29858f1878abe963b4f40a436434fTimo Sirainenstruct ostream;
ba90e657bc68a72ab3b3021e2f4a874fac9965baTimo Sirainen
45155bb1250cf5a120278f349465aded513a100fTimo Sirainenstruct http_request;
de754cb78f75e8b3b994cddafe41c9ed1467c33dTimo Sirainen
ba90e657bc68a72ab3b3021e2f4a874fac9965baTimo Sirainenstruct http_server;
ba90e657bc68a72ab3b3021e2f4a874fac9965baTimo Sirainenstruct http_server_request;
ba90e657bc68a72ab3b3021e2f4a874fac9965baTimo Sirainenstruct http_server_response;
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen/*
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen * Server settings
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen */
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainenstruct http_server_settings {
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen const char *rawlog_dir;
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen /* The maximum time in milliseconds a client is allowed to be idle before
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen it is disconnected. */
ba90e657bc68a72ab3b3021e2f4a874fac9965baTimo Sirainen unsigned int max_client_idle_time_msecs;
de754cb78f75e8b3b994cddafe41c9ed1467c33dTimo Sirainen
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen /* Maximum number of pipelined requests per connection (default = 1) */
2c5c293940fd6c7e020e1d58dae77a9d01f9059bTimo Sirainen unsigned int max_pipelined_requests;
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen
b8cd2f2f99351605725b7260f5da89cff76d0a3aTimo Sirainen /* Request limits */
f30577ff7cf29858f1878abe963b4f40a436434fTimo Sirainen struct http_request_limits request_limits;
9508ac436fff0e1dcea975855c139cd251deb703Timo Sirainen
6d24551e169c0808695db35d7a228f1970a84c75Timo Sirainen /* The kernel send/receive buffer sizes used for the connection sockets.
6d24551e169c0808695db35d7a228f1970a84c75Timo Sirainen Configuring this is mainly useful for the test suite. The kernel
01cd9d4a8050a1dbf1da2c830f9755a45d6d004aTimo Sirainen defaults are used when these settings are 0. */
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen size_t socket_send_buffer_size;
ed16ab579bd058ec5e2b5d02bb41fdadd9e05b31Timo Sirainen size_t socket_recv_buffer_size;
01cd9d4a8050a1dbf1da2c830f9755a45d6d004aTimo Sirainen
ddbdc644a15f56f4b43596f1b8c0fc196c101445Timo Sirainen /* Enable logging debug messages */
ed16ab579bd058ec5e2b5d02bb41fdadd9e05b31Timo Sirainen bool debug;
ddbdc644a15f56f4b43596f1b8c0fc196c101445Timo Sirainen};
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainen
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainen/*
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainen * Response
01cd9d4a8050a1dbf1da2c830f9755a45d6d004aTimo Sirainen */
01cd9d4a8050a1dbf1da2c830f9755a45d6d004aTimo Sirainen
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen/* Connection data for an established HTTP tunnel */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenstruct http_server_tunnel {
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen int fd_in, fd_out;
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen struct istream *input;
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen struct ostream *output;
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen};
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainentypedef void (*http_server_tunnel_callback_t)(void *context,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen const struct http_server_tunnel *tunnel);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Start creating the response for the request. This function can be called
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen only once for each request. */
26681e71837ebbb3eb92455ec4e3cadefa710f82Timo Sirainenstruct http_server_response *
26681e71837ebbb3eb92455ec4e3cadefa710f82Timo Sirainenhttp_server_response_create(struct http_server_request *req,
26681e71837ebbb3eb92455ec4e3cadefa710f82Timo Sirainen unsigned int status, const char *reason);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Add a custom header to the response. This can override headers that are
de754cb78f75e8b3b994cddafe41c9ed1467c33dTimo Sirainen otherwise created implicitly. */
de754cb78f75e8b3b994cddafe41c9ed1467c33dTimo Sirainenvoid http_server_response_add_header(struct http_server_response *resp,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen const char *key, const char *value);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Change the response code and text, cannot be used after submission */
de754cb78f75e8b3b994cddafe41c9ed1467c33dTimo Sirainenvoid http_server_response_update_status(struct http_server_response *resp,
de754cb78f75e8b3b994cddafe41c9ed1467c33dTimo Sirainen unsigned int status, const char *reason);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Set the value of the "Date" header for the response using a time_t value.
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen Use this instead of setting it directly using
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen http_server_response_add_header() */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenvoid http_server_response_set_date(struct http_server_response *resp,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen time_t date);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Assign an input stream for the outgoing payload of this response. The input
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen stream is read asynchronously while the response is sent to the client. */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenvoid http_server_response_set_payload(struct http_server_response *resp,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen struct istream *input);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Assign payload data to the response. The data is copied to the request pool.
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen If your data is already durably allocated during the existence of the
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen response, you should consider using http_server_response_set_payload() with
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen a data input stream instead. This will avoid copying the data unnecessarily.
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenvoid http_server_response_set_payload_data(struct http_server_response *resp,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen const unsigned char *data, size_t size);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Obtain an output stream for the response payload. This is an alternative to
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen using http_server_response_set_payload(). Currently, this can only return a
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen blocking output stream. The request is submitted implicitly once the output
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen stream is written to. Closing the stream concludes the payload. Destroying
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen the stream before that aborts the response and closes the connection.
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenstruct ostream *
2c5c293940fd6c7e020e1d58dae77a9d01f9059bTimo Sirainenhttp_server_response_get_payload_output(struct http_server_response *resp,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen bool blocking);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Get the status code and reason string currently set for this response. */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenvoid http_server_response_get_status(struct http_server_response *resp,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen int *status_r, const char **reason_r);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Get the total size of the response when sent over the connection. */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenuoff_t http_server_response_get_total_size(struct http_server_response *resp);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Add authentication challenge to the response. */
de754cb78f75e8b3b994cddafe41c9ed1467c33dTimo Sirainenvoid http_server_response_add_auth(
de754cb78f75e8b3b994cddafe41c9ed1467c33dTimo Sirainen struct http_server_response *resp,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen const struct http_auth_challenge *chlng);
de754cb78f75e8b3b994cddafe41c9ed1467c33dTimo Sirainen/* Add "Basic" authentication challenge to the response. */
de754cb78f75e8b3b994cddafe41c9ed1467c33dTimo Sirainenvoid http_server_response_add_auth_basic(
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen struct http_server_response *resp, const char *realm);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Submit the response. It is queued for transmission to the client. */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenvoid http_server_response_submit(struct http_server_response *resp);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Submit the response and close the connection once it is sent. */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenvoid http_server_response_submit_close(struct http_server_response *resp);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Submit the response and turn the connection it is sent across into a tunnel
d229d26d263a57a77eec8fe7cba24fbfd9509966Timo Sirainen once it is sent successfully. The callback is called once that happens. */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenvoid http_server_response_submit_tunnel(struct http_server_response *resp,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen http_server_tunnel_callback_t callback, void *context);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Submits response and blocks until provided payload is sent. Multiple calls
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen are allowed; payload is sent in chunks this way. Payload transmission is
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen finished with http_server_response_finish_payload(). If the sending fails,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen returns -1 and sets resp=NULL to indicate that the response was freed,
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen otherwise returns 0 and resp is unchanged.
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen An often more convenient ostream wrapper API is available as
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen http_server_response_get_payload_output() with blocking=TRUE.
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen */
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainenint http_server_response_send_payload(struct http_server_response **resp,
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen const unsigned char *data, size_t size);
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen/* Finish sending the payload. Always frees resp and sets it to NULL.
d7cd49f01fad7c87c5a0865ebf54a548275e9feeTimo Sirainen Returns 0 on success, -1 on error. */
d7cd49f01fad7c87c5a0865ebf54a548275e9feeTimo Sirainenint http_server_response_finish_payload(struct http_server_response **resp);
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen/* Abort response payload transmission prematurely. This closes the associated
3612ee5c737954d5fb88fd1775aad80f7bf1dc4eTimo Sirainen connection */
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainenvoid http_server_response_abort_payload(struct http_server_response **resp);
f30577ff7cf29858f1878abe963b4f40a436434fTimo Sirainen
b8cd2f2f99351605725b7260f5da89cff76d0a3aTimo Sirainen/*
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen * Request
45155bb1250cf5a120278f349465aded513a100fTimo Sirainen */
45155bb1250cf5a120278f349465aded513a100fTimo Sirainen
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen/* Get the parsed HTTP request information for this request. */
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainenconst struct http_request *
f30577ff7cf29858f1878abe963b4f40a436434fTimo Sirainenhttp_server_request_get(struct http_server_request *req);
01cd9d4a8050a1dbf1da2c830f9755a45d6d004aTimo Sirainen
01cd9d4a8050a1dbf1da2c830f9755a45d6d004aTimo Sirainen/* Reference a server request */
f30577ff7cf29858f1878abe963b4f40a436434fTimo Sirainenvoid http_server_request_ref(struct http_server_request *req);
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen/* Unreference a server request. Returns TRUE if there are still more
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen references, FALSE if not. */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenbool http_server_request_unref(struct http_server_request **_req);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Set flag that determines whether the connection is closed after the
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen request is handled. */
ccef83820a01bb37ad48653a05a9c5aa6560826aTimo Sirainenvoid http_server_request_connection_close(struct http_server_request *req,
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen bool close);
3612ee5c737954d5fb88fd1775aad80f7bf1dc4eTimo Sirainen
ccef83820a01bb37ad48653a05a9c5aa6560826aTimo Sirainen/* Get the pool for this request. */
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainenpool_t http_server_request_get_pool(struct http_server_request *req);
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen/* Returns the response created for the request with
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen http_server_response_create(), or NULL if none. */
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainenstruct http_server_response *
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainenhttp_server_request_get_response(struct http_server_request *req);
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen/* Returns TRUE if request is finished either because a response was sent
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen or because the request was aborted. */
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainenbool http_server_request_is_finished(struct http_server_request *req);
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen/* Return input stream for the request's payload. Optionally, this stream
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen can be made blocking. Do *NOT* meddle with the FD of the http_request
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen payload to achieve the same, because protocol violations will result.
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen */
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainenstruct istream *
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainenhttp_server_request_get_payload_input(struct http_server_request *req,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen bool blocking);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen/* Forward the incoming request payload to the provided output stream in the
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen background. Calls the provided callback once the payload was forwarded
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen successfully. If forwarding fails, the client is presented with an
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainen appropriate error. If the payload size exceeds max_size, the client will
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainen get a 413 error. Before the callback finishes, the application must either
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainen have added a reference to the request or have submitted a response. */
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainenvoid http_server_request_forward_payload(struct http_server_request *req,
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainen struct ostream *output, uoff_t max_size,
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainen void (*callback)(void *), void *context);
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainen#define http_server_request_forward_payload(req, \
ab45534d66792946b5794ab99a843d2f2b1d556fTimo Sirainen output, max_size, callback, context) \
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen http_server_request_forward_payload(req, output, max_size, \
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen (void(*)(void*))callback, context + \
ac84cb764c3a6f4b4b9ded2510d425fb5744dfe8Timo Sirainen CALLBACK_TYPECHECK(callback, void (*)(typeof(context))))
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen/* Forward the incoming request payload to the provided buffer in the
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen background. Behaves identical to http_server_request_forward_payload()
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen otherwise. */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenvoid http_server_request_buffer_payload(struct http_server_request *req,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen buffer_t *buffer, uoff_t max_size,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen void (*callback)(void *), void *context);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen#define http_server_request_buffer_payload(req, \
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen buffer, max_size, callback, context) \
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen http_server_request_buffer_payload(req, buffer, max_size, \
3612ee5c737954d5fb88fd1775aad80f7bf1dc4eTimo Sirainen (void(*)(void*))callback, context + \
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen CALLBACK_TYPECHECK(callback, void (*)(typeof(context))))
e95dba8921087afebb8a92c592af3b8ca22ae796Timo Sirainen/* Handle the incoming request payload by calling the callback each time
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen more data is available. Payload reading automatically finishes when the
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen request payload is fully read. Before the final callback finishes, the
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen application must either have added a reference to the request or have
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen submitted a response. */
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainenvoid http_server_request_handle_payload(struct http_server_request *req,
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen void (*callback)(void *context), void *context);
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen#define http_server_request_handle_payload(req, callback, context) \
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen http_server_request_handle_payload(req,\
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen (void(*)(void*))callback, context + \
1093de32efb2a231949566d4bd8aa55a8f43fb70Timo Sirainen CALLBACK_TYPECHECK(callback, void (*)(typeof(context))))
b8422738d3c891c7c93294b027a5cfe7d520e378Timo Sirainen
b8422738d3c891c7c93294b027a5cfe7d520e378Timo Sirainen/* Get the authentication credentials provided in this request. Returns 0 if
b8422738d3c891c7c93294b027a5cfe7d520e378Timo Sirainen the Authorization header is absent, returns -1 when that header cannot be
ab1236617440e654d5c5a043b677512714b788ddTimo Sirainen parsed, and returns 1 otherwise */
8e50329e2c5e3a199674ae9f6d3dfcddab02487bTimo Sirainenint http_server_request_get_auth(struct http_server_request *req,
e2a88d59c0d47d63ce1ad5b1fd95e487124a3fd4Timo Sirainen struct http_auth_credentials *credentials);
ab1236617440e654d5c5a043b677512714b788ddTimo Sirainen
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen/* Send a failure response for the request with given status/reason. */
f8a78c816b4dbfda42f13d8ee152e0cdb28c6a4aTimo Sirainenvoid http_server_request_fail(struct http_server_request *req,
ab1236617440e654d5c5a043b677512714b788ddTimo Sirainen unsigned int status, const char *reason);
ab1236617440e654d5c5a043b677512714b788ddTimo Sirainen/* Send a failure response for the request with given status/reason
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen and close the connection. */
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainenvoid http_server_request_fail_close(struct http_server_request *req,
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen unsigned int status, const char *reason);
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen/* Send a failure response for the request with given status/reason/text.
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen The text is sent as the response payload, if appropriate. */
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainenvoid http_server_request_fail_text(struct http_server_request *req,
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen unsigned int status, const char *reason, const char *format, ...)
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen ATTR_FORMAT(4, 5);
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen/* Send an authentication failure response for the request with given reason.
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen The provided challenge is set in the WWW-Authenticate header of the
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen response. */
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainenvoid http_server_request_fail_auth(struct http_server_request *req,
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen const char *reason, const struct http_auth_challenge *chlng)
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen ATTR_NULL(2);
e3a838c80f54f024115fade93c6c87a0998f1fabTimo Sirainen/* Send a authentication failure response for the request with given reason.
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen The provided realm is used to construct an Basic challenge in the
9f627b360ed38fdc54cb02ec5e67246c3f0d5b0fTimo Sirainen WWW-Authenticate header of the response. */
9f627b360ed38fdc54cb02ec5e67246c3f0d5b0fTimo Sirainenvoid http_server_request_fail_auth_basic(struct http_server_request *req,
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen const char *reason, const char *realm)
00fa8dcbc66f56daa737487c9dec7166c37de79eTimo Sirainen ATTR_NULL(2);
00fa8dcbc66f56daa737487c9dec7166c37de79eTimo Sirainen
ab1236617440e654d5c5a043b677512714b788ddTimo Sirainen/* Call the specified callback when HTTP request is destroyed. This happens
ac45ba9c603b67cc43fa7bceffdef0a19100720bTimo Sirainen after one of the following:
6e8ad595d0603295f57bef576da8a3a00b55c5e2Timo Sirainen
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen a) Response and its payload is fully sent,
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen b) Response was submitted, but it couldn't be sent due to disconnection or
6e8ad595d0603295f57bef576da8a3a00b55c5e2Timo Sirainen some other error,
80980955bb1bbcc1bd73623fe0912f334194ddd2Timo Sirainen c) http_server_deinit() was called and the request was aborted
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainen
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen Note client disconnection before response is submitted isn't visible to this.
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen The request payload reading is the responsibility of the caller, which also
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen must handle the read errors by submitting a failure response. */
e248fe370c4047cee921a91b48edc37944ab0526Timo Sirainenvoid http_server_request_set_destroy_callback(struct http_server_request *req,
8372fc7efb6d64dff2e5f55fb4a3822c56869cfeTimo Sirainen void (*callback)(void *),
3612ee5c737954d5fb88fd1775aad80f7bf1dc4eTimo Sirainen void *context);
ba90e657bc68a72ab3b3021e2f4a874fac9965baTimo Sirainen#define http_server_request_set_destroy_callback(req, callback, context) \
9f627b360ed38fdc54cb02ec5e67246c3f0d5b0fTimo Sirainen http_server_request_set_destroy_callback(req, (void(*)(void*))callback, context + \
9f627b360ed38fdc54cb02ec5e67246c3f0d5b0fTimo Sirainen CALLBACK_TYPECHECK(callback, void (*)(typeof(context))))
9f627b360ed38fdc54cb02ec5e67246c3f0d5b0fTimo Sirainen
9f627b360ed38fdc54cb02ec5e67246c3f0d5b0fTimo Sirainen/*
9f627b360ed38fdc54cb02ec5e67246c3f0d5b0fTimo Sirainen * 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 */
uoff_t input, output;
};
/* 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_request)(void *context, struct http_server_request *req);
void (*handle_connect_request)(void *context,
struct http_server_request *req, struct http_url *target);
/* Called once the connection is destroyed. */
void (*connection_destroy)(void *context, const char *reason);
};
/* Create a HTTP server connection object for the provided fd pair. The
callbacks structure is described above. */
struct http_server_connection *
http_server_connection_create(struct http_server *server,
int fd_in, int fd_out, bool ssl,
const struct http_server_callbacks *callbacks, void *context);
/* Reference the connection */
void http_server_connection_ref(struct http_server_connection *conn);
/* Dereference the connection. Returns FALSE if unrefing destroyed the
connection entirely */
bool http_server_connection_unref(struct http_server_connection **_conn);
/* Dereference and close the connection. The provided reason is passed to the
connection_destroy() callback. */
void http_server_connection_close(struct http_server_connection **_conn,
const char *reason);
/* Get the current statistics for this connection */
const struct http_server_stats *
http_server_connection_get_stats(struct http_server_connection *conn);
/*
* Server
*/
struct http_server *http_server_init(const struct http_server_settings *set);
void http_server_deinit(struct http_server **_server);
/* Shut down the server; accept no new requests and drop connections once
they become idle */
void http_server_shut_down(struct http_server *server);
/* Switch this server to the current ioloop */
void http_server_switch_ioloop(struct http_server *server);
#endif