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 820b57a3f698a088b631c0b036d3fd81c36b6a30
parent 5eaf664c617dd8b33047b9e86903fd86f059d7c4
Author: Frederic Cambus <fred@statdns.com>
Date:   Tue,  9 Oct 2018 16:32:25 +0200

Various errors + typos fixes, and minor improvements

Signed-off-by: Joris Vink <joris@coders.se>

Diffstat:
api/buffers.md | 2+-
api/http.md | 22+++++++++++-----------
api/memory.md | 4++--
api/miscellaneous.md | 2+-
api/pgsql.md | 14++++++--------
api/pools.md | 2+-
api/python.md | 16++++++++--------
api/tasks.md | 2+-
applications/README.md | 3+--
applications/buildconf_reference.md | 5++---
applications/integrated_tools.md | 2+-
applications/koreconf.md | 8++++----
applications/running.md | 6+++---
install.md | 2+-
14 files changed, 43 insertions(+), 47 deletions(-)

diff --git a/api/buffers.md b/api/buffers.md @@ -137,7 +137,7 @@ Nothing char *kore_buf_stringify(struct kore_buf *buf, size_t *length) ``` ### Description -Returns the data in a buffer as a C string. The result is NUL-terminated before it is returning to the caller. The caller should not free this data. +Returns the data in a buffer as a C string. The result is NUL-terminated before it is returned to the caller. The caller should not free this data. | Parameter | Description | | -- | -- | diff --git a/api/http.md b/api/http.md @@ -41,13 +41,13 @@ void http_response_stream(struct http_request *req, int status, void *base, size Creates an HTTP response for an HTTP request much like _http\_response\(\)_. -However unlike that function this one does not copy the response body data but rather stream from it. It will call the given callback _cb_ when all data has been sent. +However unlike that function this one does not copy the response body data but rather streams from it. It will call the given callback _cb_ when all data has been sent. | Parameter | Description | | --- | --- | | req | The HTTP request to respond to. | | status | The HTTP status code to include in the response. | -| base | The base pointer of the data tobe sent in the response body. | +| base | The base pointer of the data to be sent in the response body. | | length | The length of the data to be sent. | | cb | A callback that is called when all data has been sent. | | arg | A user supplied argument that is passed in the callback. | @@ -158,7 +158,7 @@ Read file data from the given file up to _length_ size. ### Returns -Returns the number of bytes successfully read from the file or 0 on end of file or -1 on error. +Returns the number of bytes successfully read from the file, or 0 on end of file, or -1 on error. --- @@ -196,7 +196,7 @@ void http_populate_post(struct http_request *req) Processes an HTTP POST by taking the HTTP body and parsing it according to _application/x-www-form-urlencoded_. -This function will automatically match any fields found against configured validators to check if they contained sensible date. If the validators fail the field is automatically removed. +This function will automatically match any fields found against configured validators to check if they contained sensible data. If the validators fail the field is automatically removed. | Parameter | Description | | --- | --- | @@ -427,7 +427,7 @@ KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not ### Synopsis ``` -int http_argument_get_uint16(struct http_request *req, const char *name, int16_t *out) +int http_argument_get_uint16(struct http_request *req, const char *name, uint16_t *out) ``` ### Description @@ -451,7 +451,7 @@ KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not ### Synopsis ``` -int http_argument_get_int32(struct http_request *req, const char *name, int16_t *out) +int http_argument_get_int32(struct http_request *req, const char *name, int32_t *out) ``` ### Description @@ -475,7 +475,7 @@ KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not ### Synopsis ``` -int http_argument_get_uint32(struct http_request *req, const char *name, int16_t *out) +int http_argument_get_uint32(struct http_request *req, const char *name, uint32_t *out) ``` ### Description @@ -499,7 +499,7 @@ KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not ### Synopsis ``` -int http_argument_get_int64(struct http_request *req, const char *name, int16_t *out) +int http_argument_get_int64(struct http_request *req, const char *name, int64_t *out) ``` ### Description @@ -523,7 +523,7 @@ KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not ### Synopsis ``` -int http_argument_get_uint64(struct http_request *req, const char *name, int16_t *out) +int http_argument_get_uint64(struct http_request *req, const char *name, uint64_t *out) ``` ### Description @@ -547,7 +547,7 @@ KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not ### Synopsis ``` -int http_argument_get_uint64(struct http_request *req, const char *name, float *out) +int http_argument_get_float(struct http_request *req, const char *name, float *out) ``` ### Description @@ -571,7 +571,7 @@ KORE\_RESULT\_OK if the argument was found or KORE\_RESULT\_ERROR if it was not ### Synopsis ``` -int http_argument_get_uint64(struct http_request *req, const char *name, double *out) +int http_argument_get_double(struct http_request *req, const char *name, double *out) ``` ### Description diff --git a/api/memory.md b/api/memory.md @@ -2,7 +2,7 @@ The memory system in Kore for heap allocation is based on pools. At startup Kore will initialize at least 10 pools for commonly sized objects \(ranging from 8 to 8192 bytes\). -Any data allocated via _kore\_malloc\(\)_, _kore\_strdup\(\)_ or _kore\_realloc\(\)_ comes from the common pools unless it is larger then 8192 in which case _calloc\(\)_ is used. +Any data allocated via _kore\_malloc\(\)_, _kore\_strdup\(\)_ or _kore\_realloc\(\)_ comes from the common pools unless it is larger than 8192 in which case _calloc\(\)_ is used. --- @@ -61,7 +61,7 @@ void *kore_realloc(void *ptr, size_t length) ### Description -Grows or shrinks a existing allocated memory pointer. +Grows or shrinks an existing allocated memory pointer. | Parameter | Description | | --- | --- | diff --git a/api/miscellaneous.md b/api/miscellaneous.md @@ -40,7 +40,7 @@ Bounded C string copying. The result is always NUL-terminated. | length | The maximum number of bytes that the destination buffer holds. | ### Returns -The length of the original string. If this length is equal or larger then the destination buffer then truncation of the string has occurred. +The length of the original string. If this length is equal or larger than the destination buffer then truncation of the string has occurred. --- diff --git a/api/pgsql.md b/api/pgsql.md @@ -1,6 +1,6 @@ # Pgsql -The pgsql API in Kore allows you to use Postgresql in a straight forward manner. It supports both synchronous and asynchronous queries. +The pgsql API in Kore allows you to use PostgreSQL in a straight forward manner. It supports both synchronous and asynchronous queries. Note that you must have built Kore with PGSQL=1 in order to use this API. @@ -67,8 +67,7 @@ void kore_pgsql_bind_request(struct kore_pgsql *pgsql, struct http_request *req) ### Description -Bind a kore\_pgsql data structure to an HTTP request. This causes the HTTP request to be notified for any changes to the pgsql -data structure. +Bind a kore\_pgsql data structure to an HTTP request. This causes the HTTP request to be notified for any changes to the pgsql data structure. | Parameter | Description | | --- | --- | @@ -86,13 +85,12 @@ Nothing. ### Synopsis ``` -void kore_pgsql_bind_callback(struct kore_pgsql *pgsql, void (*cb)(struct kore_pgsql *, void *), void *ar) +void kore_pgsql_bind_callback(struct kore_pgsql *pgsql, void (*cb)(struct kore_pgsql *, void *), void *ar) ``` ### Description -Bind a kore\_pgsql data structure to a callback function. This function is called for any state change related to the -pgsql data structure. +Bind a kore\_pgsql data structure to a callback function. This function is called for any state change related to the pgsql data structure. | Parameter | Description | | --- | --- | @@ -171,7 +169,7 @@ Register a database connection. | Parameter | Description | | --- | --- | | dbname | The name to give to this connection. | -| connstring | A postgresql connection string. | +| connstring | A PostgreSQL connection string. | ### Returns @@ -212,7 +210,7 @@ void kore_pgsql_cleanup(struct kore_pgsql *pgsql) ### Description -Cleanup a previously initialize pgsql data structure and relinquish the database connection it held. +Cleanup a previously initialized pgsql data structure and relinquish the database connection it held. | Parameter | Description | | --- | --- | diff --git a/api/pools.md b/api/pools.md @@ -56,7 +56,7 @@ Obtain a pointer to a free element from the given pool. If a pool runs out of fr | pool | A pointer to a pool. | ### Returns -Returns a pointer to an area that is large enough to hold the data length the pool was initializes with. +Returns a pointer to an area that is large enough to hold the data length the pool was initialized with. --- diff --git a/api/python.md b/api/python.md @@ -7,8 +7,8 @@ Python 3.6 or higher should be used. --- -# Pulling in python files -You can import python files into your Kore application using the +# Pulling in Python files +You can import Python files into your Kore application using the **python_import** configuration option: ``` @@ -57,7 +57,7 @@ this worker process. ## <a name="koremoduleconstants"></a>Constants -The kore module exports some constant that can be used by the Python code. +The kore module exports some constants that can be used by the Python code. * LOG\_INFO * LOG\_NOTICE @@ -142,14 +142,14 @@ kore.websocket_broadcast(src, op, data, scope) ### Description -Broadcast a websocket message to all other connected websocket clients. +Broadcasts a websocket message to all other connected websocket clients. | Parameter | Description | | --- | --- | | src | The source **kore.connection** object. | | op | The websocket op type. | | data | The data to be broadcasted. | -| scope | Wether or not this is broadcasted to all workers or just this one. | +| scope | Whether or not this is broadcasted to all workers or just this one. | ### Returns @@ -198,7 +198,7 @@ kore.register_database("db", "host=/tmp dbname=hello") # <a name="httpmodule"></a>HTTP Like the C API Kore will pass an http\_request data structure to your -Python page handler. This data structure is of type **kore.http\_request** +Python page handler. This data structure is of type **kore.http\_request**. ## <a name="httpmoduleconstants"></a>Constants @@ -216,7 +216,7 @@ Python page handler. This data structure is of type **kore.http\_request** * agent - The user agent as a unicode string. * path - The requested path as a unicode string. * body - The entire incoming HTTP body as a PyBuffer. -* method - The requested method as an PyLong. (kore.HTTP\_METHOD\_GET, etc). +* method - The requested method as a PyLong. (kore.HTTP\_METHOD\_GET, etc). * body\_path - The path to the HTTP body on disk (if enabled). * connection - The underlying client connection as a **kore.connection** object. @@ -300,7 +300,7 @@ Creates an HTTP response for the given HTTP request. | Parameter | Description | | --- | --- | -| status | The HTTP status code to for the response. | +| status | The HTTP status code to include in the response. | | body | The HTTP body to be included in the response, this must be a binary buffer. | ### Returns diff --git a/api/tasks.md b/api/tasks.md @@ -145,7 +145,7 @@ NOTE: This is a blocking operation. | length | The maximum number of bytes that *out* can hold. | ### Returns -Returns the number of original bytes from the message, if this is larger then +Returns the number of original bytes from the message, if this is larger than the *length* parameter then truncation has occurred. --- diff --git a/applications/README.md b/applications/README.md @@ -1,3 +1,3 @@ # Applications -The chapters in this section talk about Kore applications, how to create build and run them.- \ No newline at end of file +The chapters in this section talk about Kore applications: how to create, build, and run them. diff --git a/applications/buildconf_reference.md b/applications/buildconf_reference.md @@ -1,6 +1,6 @@ # build.conf -The **build.conf** file dictates build flavors, their CFLAGS and LDFLAGS and whether or not a single binary should be constructed or not. +The **build.conf** file dictates build flavors, their CFLAGS and LDFLAGS, and whether or not a single binary should be constructed. A default **build.conf** looks like this: @@ -33,4 +33,4 @@ dev { #} ``` -There are global directives and per flavor directives as you can see in the example above. The cflags and ldflags directives are merged between global and the current active flavor.- \ No newline at end of file +There are global directives and per flavor directives as you can see in the example above. The cflags and ldflags directives are merged between global and the current active flavor. diff --git a/applications/integrated_tools.md b/applications/integrated_tools.md @@ -12,7 +12,7 @@ kodev info ### Creating an application -Creating a new application is done via the _ kodev create_ tool. This tool will create a new directory and populated it with all required files to get hacking. +Creating a new application is done via the _ kodev create_ tool. This tool will create a new directory and populate it with all required files to get hacking. The tool will automatically generate a self-signed X.509 certificate for development purposes. diff --git a/applications/koreconf.md b/applications/koreconf.md @@ -2,11 +2,11 @@ The configuration file of an application describes to Kore what modules to load, how validators work, what page handlers to map to which functions and more. -Therefor it is an integral part of Kore as a whole. +Therefore it is an integral part of Kore as a whole. Below we will quickly go over all available quick toggle configuration options, their default settings and what they do. -There are more options then 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. +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. --- @@ -78,9 +78,9 @@ By default Kore will accept as many new connections it can up to worker_max_conn > The number of OS threads to use for background tasks. **tls_version** (default: 1.2 only) -> The TLS versions allowed, by default this is set to only TLSv1.2. +> The TLS versions allowed, by default this is set to TLSv1.2 only. -**tls_cipher** (default: A very sane set of ciphersuites prefering AEAD ciphers and ephemiral key exchanges, RSA key exchanges are not enabled). +**tls_cipher** (default: A very sane set of ciphersuites preferring AEAD ciphers and ephemeral key exchanges, RSA key exchanges are not enabled). > The server TLS ciphersuites that are allowed. **tls_dhparam** (default: dh2048.pem) diff --git a/applications/running.md b/applications/running.md @@ -7,7 +7,7 @@ Starting Kore applications is done in one or two ways: The first method will keep the process in the foreground allowing you to shut it down using CTRL-C. -This method is aimed when developing. +This method is aimed at developing. The second method will read the configuration file passed on the command line, load in all required application modules and attempt to change root and drop privileges accordingly. @@ -18,10 +18,10 @@ You can skip chroot\(\) and privdrops using -n and -r. ### Random **Important** If you are running Kore chrooted and privilege seperated (which -you **should** be doing production) Kore will require /dev/urandom to be +you **should** be doing production), Kore will require /dev/urandom to be created under the chroot environment for both the keymgr and worker processes. -Failing to do so will make your setup not work. +Failing to do so will prevent your application from working. ### Halting applications diff --git a/install.md b/install.md @@ -19,7 +19,7 @@ Get the 3.0.0 release tarball and signature from [https://kore.io/releases/3.0.0 minisign -Vm kore-3.0.0.tgz -P RWSxkEDc2y+whfKTmvhqs/YaFmEwblmvar7l6RXMjnu6o9tZW3LC0Hc9 ``` -If verification is successfull, build it. Do not build distributions that +If verification is successful, build it. Do not build distributions that cannot be verified by the minisign key seen above. ```