kore-doc

The kore documentation found under https://docs.kore.io/
Commits | Files | Refs | README | git clone https://git.kore.io/kore-doc.git

commit ec131a1ab3e29d496e9c19dd81a497cea101ac31
parent a6b7c543456014be45c42f8325627b5b3c990e92
Author: Joris Vink <joris@coders.se>
Date:   Mon, 29 Jun 2020 09:37:13 +0200

add latest

Diffstat:
README.md | 2++
api/json.md | 299+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
api/python.md | 66+++++++++++++++++++++++++++++++++++++++++++++++++-----------------
applications/building.md | 2+-
applications/koreconf.md | 36+++++++++++++++++++++++++++++-------
applications/the-pyko-tool.md | 6------
install.md | 13+++++++------
7 files changed, 387 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md @@ -15,11 +15,13 @@ This documentation is for the 4.0.0 release. * TLS enabled by default. * Optional background tasks. * Built-in parameter validation. +* Automatic HTTPS (via ACME protocol). * Fully privilege separated by default. * Optional asynchronous PostgreSQL support. * Private keys isolated in separate process \(RSA and ECDSA\). * Default sane TLS ciphersuites \(PFS in all major browsers\). * Modules can be reloaded on-the-fly, even while serving content. +* Worker processes sandboxed on OpenBSD (pledge) and Linux (seccomp). * Optional support for page handlers in Python with async/await support. * Event driven \(epoll/kqueue\) architecture with per CPU worker processes. * Build your web application as a precompiled dynamic library or single binary. diff --git a/api/json.md b/api/json.md @@ -0,0 +1,299 @@ +# JSON parser + +Kore provides a built-in JSON parser for your applications. + +## Index + +* [kore\_json\_init](#init) +* [kore\_json\_cleanup](#cleanup) +* [kore\_json\_parse](#parse) +* [kore\_json\_find\_object](#findobject) +* [kore\_json\_find\_array](#findarray) +* [kore\_json\_find\_string](#findstring) +* [kore\_json\_find\_number](#findnumber) +* [kore\_json\_find\_literal](#findliteral) + +* [kore\_json\_create\_object](#createobject) +* [kore\_json\_create\_array](#createarray) +* [kore\_json\_create\_string](#createstring) +* [kore\_json\_create\_number](#createnumber) +* [kore\_json\_create\_literal](#createliteral) + +* [kore\_json\_strerror](#strerror) + +## Examples + +See the included [example](https://github.com/jorisvink/kore/tree/master/examples/json) in the Kore source tree for an example on how to use this API. + +--- + +# kore\_curl\_init {#init} +### Synopsis +``` +void kore_curl_init(struct kore_curl *client, const char *url); +``` +### Description +Initializes a **kore\_curl** context. This must be called before any other +function can be safely used. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | +| url | The URL to be associated with this context. | + +### Settings {#settings} + +By default this function will set the following libcurl options: +(some of these are **required** by the Kore curl API to function, it is +advised you do not override these). + +- CURLOPT\_NOSIGNAL is set to 1. +- CURLOPT\_URL is set to the URL passed. +- CURLOPT\_USERAGENT is set to "kore/version". +- CURLOPT\_PRIVATE is set to the kore\_client data structure. +- CURLOPT\_WRITEFUNCTION is set to the kore\_curl\_tobuf function. +- CURLOPT\_ERRORBUFFER is set to point to the internal error buffer. +- CURLOPT\_TIMEOUT is set to the configuration option value curl\_timeout. +- CURLOPT\_WRITEDATA is set to the response kore buffer of the data structure. + +### Returns +Nothing + +--- +# kore\_curl\_cleanup {#cleanup} +### Synopsis +``` +void kore_curl_cleanup(struct kore_curl *client); +``` +### Description +Cleanup the **kore\_curl** context and release all resources. This must be +called when you no longer need the context. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | + +### Returns +Nothing + +--- +# kore\_curl\_bind\_request {#bindrequest} +### Synopsis +``` +void kore_curl_bind_request(struct kore_curl *client, struct http_request *req); +``` +### Description +Bind an HTTP request to a kore\_curl request. Binding means that the HTTP +request will be woken up by Kore once the curl request has a result. + +Using this in combination with the HTTP state machine allows you to build +request handlers in a completely asynchronous fashion. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | +| req | The HTTP request to be bound to the task. | + +### Returns +Nothing + +--- +# kore\_curl\_bind\_callback {#bindcallback} +### Synopsis +``` +void kore_curl_bind_callback(struct kore_curl *client, + void (*cb)(struct kore_curl *, void *), void *arg) +``` +### Description +Bind a callback to a curl request. Much like the HTTP binding this will cause +Kore to call this callback once a curl request has a result. + +You may **not** bind both a callback and an HTTP request. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | +| cb | The callback to call. | +| arg | User-supplied pointer that is passed to the callback. | + +### Returns +Nothing + +--- +# kore\_curl\_run {#run} +### Synopsis +``` +void kore_curl_run(struct kore_curl *client) +``` +### Description +Schedules the kore\_curl context onto the event loop. After calling this +Kore will wake-up the bound HTTP request or call the bound callback once +there is a result. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | + +### Returns +Nothing + +--- +# kore\_curl\_success {#success} +### Synopsis +``` +int kore_curl_success(struct kore_curl *client) +``` +### Description +Check if a curl request was successful (checks if the curl handle is CURLE\_OK). + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | + +### Returns +Returns 1 if the curl handle its result value was CURLE\_OK or 0 otherwise. + +--- +# kore\_curl\_logerror {#logerror} +### Synopsis +``` +void kore_curl_logerror(struct kore_task *client) +``` +### Description +Log a notice with the error that the curl handle has returned. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | + +### Returns +Nothing + +--- +# kore\_curl\_strerror {#strerror} +### Synopsis +``` +const char *kore_curl_strerror(struct kore_task *client) +``` +### Description +Returns a pointer to a human readable error string set by libcurl. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | + +### Returns +A pointer to a human readable error string. + +--- + +# kore\_curl\_response\_as\_bytes {#responsebytes} +### Synopsis +``` +void kore_curl_response_as_bytes(struct kore_curl *client, const u_int8_t **body, size_t *len) +``` +### Description +Obtain the response from a curl request as plain bytes. The **bytes** and **len** pointers are populated to point to the response that was obtained. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | +| body | Pointer which will be pointed to the response bytes. | +| len | Pointer to a size\_t that will contain the length of the response. | + +### Returns +Nothing + +--- + +# kore\_curl\_response\_as\_string {#responsestring} +### Synopsis +``` +char *kore_curl_response_as_string(struct kore_curl *client); +``` +### Description +Obtain the response from a curl request as a pointer to a C string. + +You must not free the returned pointer. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | + +### Returns +A pointer to the response as a C string. + +--- + +# kore\_curl\_http\_setup {#httpsetup} +### Synopsis +``` +void kore_curl_http_setup(struct kore_curl *client, int method, const void *data, size_t len); +``` +### Description +Setup an HTTP client request. You must have called [kore\_curl\_init()](#init) first. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | +| method | The HTTP method to be used, see [below](#httpmethod) | +| data | Pointer to the HTTP body to be sent (may be NULL). | +| len | The length of the HTTP body data (may be 0). | + +### HTTP methods {#httpmethod} + +Supported HTTP methods are: + +- HTTP\_METHOD\_GET +- HTTP\_METHOD\_PUT +- HTTP\_METHOD\_HEAD +- HTTP\_METHOD\_POST +- HTTP\_METHOD\_PATCH +- HTTP\_METHOD\_DELETE +- HTTP\_METHOD\_OPTIONS + +### Returns +Nothing + +--- + +# kore\_curl\_http\_set\_header {#setheader} +### Synopsis +``` +void kore_curl_http_set_header(struct kore_curl *client, const char *header. const char *value); +``` +### Description +Add an HTTP header to a configured HTTP client request. + +If value is NULL or an empty string the header is removed. + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | +| header | The HTTP header name. | +| value | The HTTP header value. | + +### Returns +Nothing + +--- + +# kore\_curl\_http\_get\_header {#getheader} +### Synopsis +``` +int kore_curl_http_get_header(struct kore_curl *client, const char *header. const char **out); +``` +### Description +Obtain an HTTP header from the response (if [kore\_curl\_success()](#success) was 1). + +| Parameter | Description | +| -- | -- | +| client | A kore\_curl data structure. | +| header | The HTTP header name. | +| out | A pointer which will receive the pointer to the HTTP header value. | + +### Returns + +Returns KORE\_RESULT\_OK if the header was found, or KORE\_RESULT\_ERROR if not. + +--- diff --git a/api/python.md b/api/python.md @@ -7,47 +7,79 @@ Python 3.6 or higher should be used. --- -# Pulling in Python files -You can import Python files into your Kore application using the -**python_import** configuration option: +# A Kore Python application -``` -python_import ./src/hello.py -``` +Since the 4.0.0 release you can use Kore as an asynchronous first +Python web development platform. -If you would like to add a search path for modules (PYTHONPATH) you can -specify this using the **python\_path** configuration option: +Completely configurable via code and easy to setup and write. -``` -python_path /var/site-packages/mymodules/ -``` +A Kore Python application must be setup in the following way: -# Intro -Before you write any Python code you must import the kore module: -```python -import kore -``` +* Import kore. +* Define a class with a configure() method. +* Instanciate the koreapp global with that class. + +The configure() method is called at startup by the Kore platform and +will receive a list of arguments passed to the command-line. + +From there you can configure Kore via the kore.config object, create +server contexts and setup domains and routes. Note that the Python code is expected to run inside of the Kore worker process, the kore module being imported is not available outside of this worker process. +Example: + +```python +import kore + +class MyApp: + def configure(self, args): + kore.config.workers = 1 + kore.config.deployment = "dev" + + kore.server("notls", ip="127.0.0.1", port="8888", tls=False) + + domain = kore.domain("*", attach="notls") + domain.route("/", self.index, methods=["get"]) + domain.route("^/(0-9)$", self.index_with_args, methods=["get"]) + + def index(self, req): + req.response(200, b'hello') + + def index_with_args(self, req, specified_id): + req.response(200, specified_id) + +koreapp = MyApp() +``` + ## Index * [Kore module](#koremodule) + * [functions](#functions) TODO * [constants](#koremoduleconstants) * [functions](#koremodulefunctions) + * [server](#server) TODO + * [domain](#domain) TODO * [log](#log) * [timer](#timer) * [proc](#proc) * [fatal](#fatal) * [tracer](#tracer) * [task\_create](#taskcreate) + * [task\_kill](#taskkill) TODO * [gather](#gather) * [suspend](#suspend) * [httpclient](#httpclient) - * [register\_database](#registerdatabase) + * [curl](#curl) TODO + * [dbsetup](#dbsetup) TODO * [websocket\_broadcast](#websocketbroadcast) + * [worker](#worker) TODO + * [setname](#setname) TODO + * [coroname](#coroname) TODO + * [corotrace](#corotrace) TODO * [Http module](#httpmodule) diff --git a/applications/building.md b/applications/building.md @@ -52,5 +52,5 @@ kore_source = /path/to/kore/source/ kore_flavor = <flavors..> ``` -This will cause _kore build_ to build the original Kore source code and link your application logic directly into it. It will also add in the configuration file and of course any assets that are under the **assets** directory. The result is a single dynamically linked binary that can be run. +This will cause _kodev build_ to build the original Kore source code and link your application logic directly into it. It will also add in the configuration file and of course any assets that are under the **assets** directory. The result is a single dynamically linked binary that can be run. diff --git a/applications/koreconf.md b/applications/koreconf.md @@ -4,6 +4,35 @@ The configuration file of an application describes to Kore what modules to load, Therefore it is an integral part of Kore as a whole. +# Server context + +A server context sets up a one or more listeners for the Kore server. These +listeners can either be ipv4/ipv6 addresses or unix sockets. + +The old bind and bind_unix configuration options have been migrated since +Kore 4.0.0 to these server contexts. + +You can also turn off TLS in a server context by specifying the **tls no** +option inside of a context. + +Example: + +``` +server tls { + bind 127.0.0.1 443 + bind ::1 443 + bind_unix /var/run/socket.path + bind_unix @linux-abstract-socket +} + +server notls { + bind 127.0.0.1 80 + tls no +} +``` + +# Configuration options. + Below we will quickly go over all available quick toggle configuration options, their default settings and what they do. There are more options than what is listed below, specifically for validators, authentication blocks and domains. Please find those in https://github.com/jorisvink/kore/blob/master/conf/kore.conf.example. @@ -13,13 +42,6 @@ There are more options than what is listed below, specifically for validators, a **socket_backlog** > Maximum length to queue pending connections (see listen(2)). Must be set before any bind directives. -**bind** -> Bind to a given IP address and port number. - -**bind_unix** -> Bind to a given unix path. On Linux if this is prefixed with an '@' the -> socket will become an abstract socket. - **root** > The directory the worker processes will chroot() or chdir() into. diff --git a/applications/the-pyko-tool.md b/applications/the-pyko-tool.md @@ -1,6 +0,0 @@ -# The pyko tool - -The pyko tool that comes with Kore - - - diff --git a/install.md b/install.md @@ -16,7 +16,10 @@ Basic compilation requires the following libraries: Get the 4.0.0 release tarball and signature from [https://kore.io/releases/4.0.0](https://kore.io/releases/4.0.0) and verify it using minisign: ``` -minisign -Vm kore-4.0.0.tar.gz -P RWSxkEDc2y+whfKTmvhqs/YaFmEwblmvar7l6RXMjnu6o9tZW3LC0Hc9 +minisign -Vm kore-4.0.0.tgz -P RWSxkEDc2y+whfKTmvhqs/YaFmEwblmvar7l6RXMjnu6o9tZW3LC0Hc9 + + + ``` If verification is successful, build it. Do not build distributions that @@ -31,10 +34,10 @@ $ sudo make install Kore has several build flavors available: * CURL=1 \(compiles in asynchronous curl support\) +* ACME=1 \(compiles in ACME support\) * TASKS=1 \(compiles in task support\) * PGSQL=1 \(compiles in pgsql support\) * DEBUG=1 \(enables use of -d for debug\) -* NOTLS=1 \(compiles Kore without TLS\) * NOHTTP=1 \(compiles Kore without HTTP support\) * NOOPT=1 \(disable compiler optimizations\) * JSONRPC=1 \(compiles in JSONRPC support\) @@ -66,7 +69,4 @@ Kore is available on Homebrew under macOS and can be installed with: ``` $ brew install kore -``` - - - +`+ \ No newline at end of file