kore

An easy to use, scalable and secure web application framework for writing web APIs in C.
Commits | Files | Refs | README | LICENSE | git clone https://git.kore.io/kore.git

commit 463ea9c6f9b46963a0f5a4f2cfd3ebf505942e63
parent ead8af3b810fdc739dd3764073efcc1a163dfa6d
Author: Joris Vink <joris@coders.se>
Date:   Wed,  5 Jun 2013 16:41:42 +0200

update README for github and split it up into docs/

Diffstat:
README | 97+++++++++++++++----------------------------------------------------------------
TODO | 6------
docs/MODULES | 61+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
docs/TODO | 6++++++
4 files changed, 85 insertions(+), 85 deletions(-)

diff --git a/README b/README @@ -1,86 +1,25 @@ Hi. -Kore is a SPDY based web server that handles dynamic content via loadable -modules. Inside the examples/ directory you will find a complete example -on how such modules are built (and some tools to help you get started). +Kore is a fast webserver that facilitates creating dynamic websites in +the C programming language. It takes away the bottleneck of constantly +loading items from disk or executing non compiled code (PHP, Perl, ...). -Kore does support normal HTTP over SSL as well. -(for the less technological advanced browsers). +With a site loaded as a module in memory the page callbacks are directly called from the worker proceses and requests can be handled incredibly fast. -Take a look at example.conf as well for an overview of the way a site -is configured and setup. +No overhead. -Right now Kore development is a moving process, so expect bugs. -If you run into said bugs please contact me at joris@coders.se. - -To get started put some X.509 certificates in a folder called certs -and run a make to get everything compiled. If if doesn't compile out of -the box there's something you can help me out with. - -You can tell kore to reload its site module by sending a SIGHUP signal -to the main process. Sending a SIGQUIT signal will reap all worker -processes and shutdown the server. - -I should add a TODO list. - -Page to function mapping -======================== -In the configuration file you specify how pages on your site are -mapped to what callback in your module. - -static /profile.html serve_profile - -The above example binds the callback serve_profile() to the profile.html page. -Kore automatically calls this callback when the page is requested by a client. - -All callbacks must be based on this prototype: - int callback(struct http_request *); - -Callback functions MUST return either KORE_RESULT_OK, -KORE_RESULT_ERROR or KORE_RESULT_RETRY. - -KORE_RESULT_OK will cleanup the request and remove it. -KORE_RESULT_ERROR will disconnect the client immediately after returning. -KORE_RESULT_RETRY will reschedule the callback to be called again. - -Most of the times KORE_RESULT_ERROR or KORE_RESULT_OK should come from: - int http_response(struct http_request *req, - int status, u_int8_t *data, u_int32_t datalen); +Features + Supports SPDY/3 + Supports HTTP/1.1 + Secure by default + SSL connections only + Virtual host support + Easy to use configuration + Loads your site as a precompiled C module + Linux epoll(7) and worker processes for throughput + Modules can be reloaded on-the-fly even while serving content -The http_response() function is used to queue up the HTTP response -(including status code and content to be sent). - -If you wish to add headers to the response do so before calling http_response(): - void http_response_header_add(struct http_request *req, - char *header, char *value); - -If your callback wants to use POST data, it should populate it first by calling: - int http_populate_arguments(struct http_request *req); - -The returned value is the number of arguments available. -After calling the populate function you can retrieve arguments by calling: - int http_argument_lookup(struct http_request *req, - const char *name, char **out); - -This will store the value of the requested argument in the out parameter. -If http_argument_lookup() returns KORE_RESULT_ERROR out will be NULL. - -Please see the example/ folder for a good overview of a module. - -Static content -============== -Static content is included directly in the module. -The example module shows how this is done. - -After adding each static component to the Makefile, it will convert it -to a .c source file and export certain symbols that can be used by the module. - -Each component gets 3 symbols: - static_[html|css]_<component_name> actual data. - static_len_[html|css]_<component_name> length of the data. - static_mtime_[html|css]_<component_name> last modified timestamp. - -API functions -============= - See includes/kore.h and includes/http.h for a definite overview. +Right now Kore development is a moving process, so expect bugs. +If you run into said bugs please contact me at patches@coders.se. +More information can be found on https://kore.io/ diff --git a/TODO b/TODO @@ -1,6 +0,0 @@ -*BSD support -Auxiliary library framework -Better logging facilities -Ability to load one module per domain -GET arguments (only POST supported) -POST multiform/form-data support diff --git a/docs/MODULES b/docs/MODULES @@ -0,0 +1,61 @@ +Page to function mapping +======================== +In the configuration file you specify how pages on your site are +mapped to what callback in your module. + +static /profile.html serve_profile + +The above example binds the callback serve_profile() to the profile.html page. +Kore automatically calls this callback when the page is requested by a client. + +All callbacks must be based on this prototype: + int callback(struct http_request *); + +Callback functions MUST return either KORE_RESULT_OK, +KORE_RESULT_ERROR or KORE_RESULT_RETRY. + +KORE_RESULT_OK will cleanup the request and remove it. +KORE_RESULT_ERROR will disconnect the client immediately after returning. +KORE_RESULT_RETRY will reschedule the callback to be called again. + +Most of the times KORE_RESULT_ERROR or KORE_RESULT_OK should come from: + int http_response(struct http_request *req, + int status, u_int8_t *data, u_int32_t datalen); + +The http_response() function is used to queue up the HTTP response +(including status code and content to be sent). + +If you wish to add headers to the response do so before calling http_response(): + void http_response_header_add(struct http_request *req, + char *header, char *value); + +If your callback wants to use POST data, it should populate it first by calling: + int http_populate_arguments(struct http_request *req); + +The returned value is the number of arguments available. +After calling the populate function you can retrieve arguments by calling: + int http_argument_lookup(struct http_request *req, + const char *name, char **out); + +This will store the value of the requested argument in the out parameter. +If http_argument_lookup() returns KORE_RESULT_ERROR out will be NULL. + +Please see the example/ folder for a good overview of a module. + +Static content +============== +Static content is included directly in the module. +The example module shows how this is done. + +After adding each static component to the Makefile, it will convert it +to a .c source file and export certain symbols that can be used by the module. + +Each component gets 3 symbols: + static_[html|css]_<component_name> actual data. + static_len_[html|css]_<component_name> length of the data. + static_mtime_[html|css]_<component_name> last modified timestamp. + +API functions +============= + See includes/kore.h and includes/http.h for a definite overview. + diff --git a/docs/TODO b/docs/TODO @@ -0,0 +1,6 @@ +*BSD support +Auxiliary library framework +Better logging facilities +Ability to load one module per domain +GET arguments (only POST supported) +POST multiform/form-data support