From ba2388c0498617c519939e325cb59631d2e6ef0f Mon Sep 17 00:00:00 2001 From: Ciprian Dorin Craciun Date: Fri, 16 Aug 2019 09:27:38 +0300 Subject: [PATCH] [documentation] Update documentation with newly introduced options --- documentation/readme.rst | 60 ++++++++++++++++++++++++------------ sources/cmd/server/server.go | 24 +++++++++------ 2 files changed, 56 insertions(+), 28 deletions(-) diff --git a/documentation/readme.rst b/documentation/readme.rst index e17e5e3..35656c9 100644 --- a/documentation/readme.rst +++ b/documentation/readme.rst @@ -123,17 +123,23 @@ This two step phase also presents a few opportunities: :: - Usage of kawipiko-server: - - --bind : - - --processes (of slave processes) - --threads (of threads per process) + kawipiko-server --archive - --archive-inmem (memory-loaded archive file) - --archive-mmap (memory-mapped archive file) - --archive-preload (preload archive file) + --archive-inmem (memory-loaded archive file) + --archive-mmap (memory-mapped archive file) + --archive-preload (preload archive in OS cache) + + --bind : (HTTP, only HTTP/1.1) + --bind-tls : (HTTPS, only HTTP/1.1) + --bind-tls-2 : (HTTPS, with HTTP/2) + + --tls-bundle (TLS certificate bundle) + --tls-public (TLS certificate public) + --tls-private (TLS certificate private) + + --processes (of slave processes) + --threads (of threads per process) --index-all --index-paths @@ -142,29 +148,39 @@ This two step phase also presents a few opportunities: --security-headers-tls --security-headers-disable + --timeout-disable --profile-cpu --profile-mem --debug --dummy + --delay Flags ..... -``--bind`` - The IP and port to listen for requests. +``--bind ``, ``--bind-tls ``, and ``--bind-tls-2 `` + The IP and port to listen for requests with: -``--processes`` and ``--threads`` + * (HTTP) HTTP/1.1 only for ``--bind``, leveraging ``fasthttp``; + * (HTTPS) HTTP/1.1 over TLS for ``--bind-tls``, leveraging ``fasthttp``; + * (HTTPS) HTTP/2 or HTTP/1.1 over TLS for ``--bind-tls-2``, leveraging Go's ``net/http``; (this can be safely used in production, however it is not as performant as the other two options;) + +``--tls-bundle ``, ``--tls-public ``, and ``--tls-private `` (optional) + If TLS is used these options allows one to specify the certificate to use, either as a single file (the bundle) or separate files (the actual public certificate and the private key). + If one doesn't specify any of these options, an embedded self-signed certificate will be used. + +``--processes `` and ``--threads `` The number of processes and threads per each process to start. It is highly recommended to use 1 process and as many threads as there are cores. Depending on the use-case, one can use multiple processes each with a single thread; this would reduce goroutine contention if it causes problems. (However note that if using ``--archive-inmem`` each process will allocate its own copy of the database in RAM; in such cases it is highly recommended to use ``--archive-mmap``.) -``--archive`` +``--archive `` The path of the CDB file that contains the archived static website content. (It can be created with the ``kawipiko-archiver`` tool.) @@ -199,8 +215,8 @@ Flags * it is highly recommended to use ``--archive-inmem`` or ``--archive-mmap`` or else (especially if data is indexed) the net effect is that of loading everything in RAM; ``--security-headers-tls`` - Enables adding the ``Strict-Transport-Security: max-age=31536000`` and ``Content-Security-Policy: upgrade-insecure-requests`` to the response headers. - (Although at the moment ``kawipiko`` does not support HTTPS, it can be used behind a TLS terminator, load-balancer or proxy that do support HTTPS; therefore these headers instruct the browser to always use HTTPS for the served domain.) + Enables adding the ``Strict-Transport-Security: max-age=31536000`` and ``Content-Security-Policy: upgrade-insecure-requests`` to the response headers, which instruct the browser to always use HTTPS for the served domain. + (Useful even without HTTPS, when used behind a TLS terminator, load-balancer or proxy that do support HTTPS.) ``--security-headers-disable`` Disables adding a few security related headers: :: @@ -219,7 +235,13 @@ Flags This argument can be used to benchmark the raw performance of the underlying Go and ``fasthttp`` performance; this is the upper limit on the achievable performance given the underlying technologies. (From my own benchmarks ``kawipiko``'s adds only about ~15% overhead when actually serving the ``hello-world.cdb`` archive.) -``--profile-cpu`` and `--profile-mem`` +``--delay `` + Enables delaying each response with a certain amount (for example ``1s``, ``1ms``, etc.) + It can be used to simulate the real-world network latencies, perhaps to see how a site with many resources loads in various conditions. + (For example, see `an experiment `__ I made with an image made out of 1425 tiles.) + (**Highly discouraged!**) + +``--profile-cpu `` and ``--profile-mem `` Enables CPU and memory profiling using Go's profiling infrastructure. @@ -235,7 +257,7 @@ Flags :: - Usage of kawipiko-archiver: + kawipiko-archiver --sources @@ -610,6 +632,8 @@ The following is a list of the most important features: * ``_wildcard.*`` files (where ``.*`` are the regular extensions like ``.txt``, ``.html``, etc.) which will be used if an actual resource is not found under that folder; (these files respect the hierarchical tree structure, i.e. "deeper" ones override the ones closer to "root";) +* support for HTTPS, with HTTP/1.1 leveraging ``fasthttp`` and HTTP/2 leveraging Go's ``net/http``; + @@ -618,8 +642,6 @@ Pending The following is a list of the most important features that are currently missing and are planed to be implemented: -* support for HTTPS; (although for HTTPS it is strongly recommended to use a dedicated TLS terminator like HAProxy_;) - * support for custom HTTP response headers (for specific files, for specific folders, etc.); (currently only ``Content-Type``, ``Content-Length``, ``Content-Encoding`` and optionally ``ETag`` is included; additionally ``Cache-Control: public, immutable, max-age=3600`` and a few security related headers are also included;) * support for mapping virtual hosts to key prefixes; (currently virtual hosts, i.e. the ``Host`` header, are ignored;) diff --git a/sources/cmd/server/server.go b/sources/cmd/server/server.go index 0e270d4..57890b7 100644 --- a/sources/cmd/server/server.go +++ b/sources/cmd/server/server.go @@ -506,16 +506,21 @@ func main_0 () (error) { kawipiko-server - --bind : - --bind-tls : - - --processes (of slave processes) - --threads (of threads per process) - --archive - --archive-inmem (memory-loaded archive file) - --archive-mmap (memory-mapped archive file) - --archive-preload (preload archive file) + --archive-inmem (memory-loaded archive file) + --archive-mmap (memory-mapped archive file) + --archive-preload (preload archive in OS cache) + + --bind : (HTTP, only HTTP/1.1) + --bind-tls : (HTTPS, only HTTP/1.1) + --bind-tls-2 : (HTTPS, with HTTP/2) + + --tls-bundle (TLS certificate bundle) + --tls-public (TLS certificate public) + --tls-private (TLS certificate private) + + --processes (of slave processes) + --threads (of threads per process) --index-all --index-paths @@ -531,6 +536,7 @@ func main_0 () (error) { --debug --dummy + --delay ** for details see: https://github.com/volution/kawipiko#kawipiko-server