add sphinx doc for g3tiles (#202)

* add sphinx doc for g3tiles

.github/workflows/linux-musl.yml

@@ -8,6 +8,7 @@ on:
       - 'demo/**'
       - 'scripts/**'
       - 'g3proxy/doc/**'
+      - 'g3tiles/doc/**'
     branches:
       - 'master'
       - 'rel/**'

.github/workflows/linux.yml

@@ -8,6 +8,7 @@ on:
       - 'demo/**'
       - 'scripts/**'
       - 'g3proxy/doc/**'
+      - 'g3tiles/doc/**'
     branches:
       - 'master'
       - 'rel/**'

.github/workflows/macos.yml

@@ -8,6 +8,7 @@ on:
       - 'demo/**'
       - 'scripts/**'
       - 'g3proxy/doc/**'
+      - 'g3tiles/doc/**'
     branches:
       - 'master'
       - 'rel/**'

.github/workflows/sphinx.yml

@@ -1,18 +1,25 @@
-name: Sphinx-Build
+name: Sphinx-Doc
 
 on:
   push:
     paths:
       - 'g3proxy/doc/**'
+      - 'g3tiles/doc/**'
   pull_request:
     paths:
       - 'g3proxy/doc/**'
+      - 'g3tiles/doc/**'
 
 jobs:
-  g3proxy:
+  build:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        component:
+        - g3proxy
+        - g3tiles
     steps:
       - uses: actions/checkout@v4
       - uses: ammaraskar/sphinx-action@master
         with:
-          docs-folder: "g3proxy/doc/"
+          docs-folder: "${{ matrix.component }}/doc/"

.gitignore

@@ -9,9 +9,6 @@
 # generated bundled license
 LICENSE-BUNDLED
 
-# Sphinx
-g3proxy/doc/_build
-
 # deb package
 /debian/
 

g3proxy/doc/.gitignore

@@ -0,0 +1 @@
+_build/

g3proxy/doc/conf.py

@@ -1,63 +1,34 @@
 # Configuration file for the Sphinx documentation builder.
 #
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
+# For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-
 # -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'g3proxy'
-copyright = '2023, Zhang Jingqiang'
+copyright = '2024, Zhang Jingqiang'
 author = 'Zhang Jingqiang'
-
-# The full version, including alpha/beta/rc tags
 release = '1.8.0'
 
-
 # -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     "sphinx.ext.graphviz",
 ]
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 
 # -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = 'alabaster'
-# html_theme_options = {
-#     'stickysidebar': True,
-# }
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+
 # -- Custom Options ----------------------------------------------------------
 
 # Set the master document, which contains the root toctree directive.

g3proxy/doc/configuration/servers/index.rst

@@ -34,7 +34,7 @@ Servers
 Common Keys
 ===========
 
-This section describes the common keys, they may be used by many escapers.
+This section describes the common keys, they may be used by many servers.
 
 .. _conf_server_common_name:
 
@@ -96,15 +96,6 @@ Set the server to use a logger running on a shared thread.
 
 **default**: not set
 
-listen
-------
-
-**required**, **type**: :ref:`tcp listen <conf_value_tcp_listen>`
-
-Set the listen config for this server.
-
-The instance count setting will be ignored if *listen_in_worker* is correctly enabled.
-
 .. _conf_server_common_listen_in_worker:
 
 listen_in_worker

g3proxy/doc/configuration/values/tls.rst

@@ -405,6 +405,8 @@ The map is consists of the following fields:
 
   A string that will be added to the prefix when calculate the session id context sha1 hash.
 
+  **default**: not set
+
   .. versionadded:: 1.7.32
 
 * ca_certificate | client_auth_certificate

g3tiles/doc/.gitignore

@@ -0,0 +1 @@
+_build/

g3tiles/doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

g3tiles/doc/conf.py

@@ -0,0 +1,27 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'g3tiles'
+copyright = '2024, Zhang Jingqiang'
+author = 'Zhang Jingqiang'
+release = '0.3.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

g3tiles/doc/configuration/backends/dummy_close.rst

@@ -0,0 +1,12 @@
+.. _configuration_backend_dummy_close:
+
+***********
+dummy_close
+***********
+
+This is the dummy backend designed to close all requests.
+
+Config Keys
+===========
+
+There are no extra config keys for this kind of backend.

g3tiles/doc/configuration/backends/index.rst

@@ -0,0 +1,69 @@
+.. _configuration_backend:
+
+*******
+Backend
+*******
+
+The type for each backend config is *map*, with two always required keys:
+
+* :ref:`name <conf_backend_common_name>`, which specify the name of the backend.
+* :ref:`type <conf_backend_common_type>`, which specify the real type of the backend, decides how to parse other keys.
+
+There are many types of backend, each with a section below.
+
+Backends
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   dummy_close
+   keyless_quic
+   keyless_tcp
+   stream_tcp
+
+Common Keys
+===========
+
+This section describes the common keys, they may be used by many backends.
+
+.. _conf_backend_common_name:
+
+**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+
+Set the name of the backend.
+
+.. _conf_backend_common_type:
+
+**required**, **type**: str
+
+Set the type of the backend.
+
+.. _conf_backend_common_discover:
+
+discover
+--------
+
+**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+
+Set the discover that this backend should use.
+
+.. _conf_backend_common_discover_data:
+
+discover_data
+-------------
+
+**required**, **type**: :ref:`discover register data <conf_discover_register_data>`
+
+Set the data that will be registered to :ref:`discover <conf_backend_common_discover>`.
+
+.. _conf_backend_common_extra_metrics_tags:
+
+extra_metrics_tags
+------------------
+
+**optional**, **type**: :ref:`static metrics tags <conf_value_static_metrics_tags>`
+
+Set extra metrics tags that should be added to backend stats.
+
+**default**: not set

g3tiles/doc/configuration/backends/keyless_quic.rst

@@ -0,0 +1,112 @@
+.. _configuration_backend_keyless_quic:
+
+************
+keyless_quic
+************
+
+A keyless quic connect backend.
+
+This will only work with keyless tasks.
+
+Config Keys
+===========
+
+The following common keys are supported:
+
+* :ref:`discover <conf_backend_common_discover>`
+* :ref:`discover_data <conf_backend_common_discover_data>`
+* :ref:`extra_metrics_tags <conf_backend_common_extra_metrics_tags>`
+
+tls_client
+----------
+
+**required**, **type**: :ref:`rustls client config <conf_value_rustls_client_config>`
+
+Set TLS parameters for this local QUIC client.
+
+**default**: not set
+
+tls_name
+--------
+
+**optional**, **type**: :ref:`tls name <conf_value_tls_name>`
+
+Set the tls server name to verify tls certificate for all peers.
+
+If not set, the peer IP will be used.
+
+**default**: not set
+
+duration_stats
+--------------
+
+**optional**, **type**: :ref:`histogram metrics <conf_value_histogram_metrics>`
+
+Histogram metrics config for the tcp connect duration stats.
+
+**default**: set with default value
+
+request_buffer_size
+-------------------
+
+**optional**, **type**: usize
+
+Set the request buffer size of the local queue. New connections will be opened when the queue is full.
+
+**default**: 128
+
+response_timeout
+----------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the timeout value for the waiting of the response.
+
+If timeout, the request will be dropped for the local buffer and an internal error response will be send to client.
+
+**default**: 4s
+
+graceful_close_wait
+-------------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the graceful wait time duration before we close an alive connection.
+
+**default**: 10s
+
+idle_connection_min
+-------------------
+
+**optional**, **type**: usize
+
+Set the minimum number of IDLE connections in the pool.
+
+**default**: 32
+
+idle_connection_max
+-------------------
+
+**optional**, **type**: usize
+
+Set the maximum number of IDLE connections in the pool.
+
+**default**: 1024
+
+concurrent_streams
+------------------
+
+**optional**, **type**: usize
+
+Set how many bidirectional streams we will use on a single QUIC connection.
+
+**default**: 4
+
+socket_buffer
+-------------
+
+**optional**, **type**: :ref:`socket buffer config <conf_value_socket_buffer_config>`
+
+Set the buffer config for the udp socket.
+
+**default**: not set

g3tiles/doc/configuration/backends/keyless_tcp.rst

@@ -0,0 +1,103 @@
+.. _configuration_backend_keyless_tcp:
+
+***********
+keyless_tcp
+***********
+
+A keyless tcp/tls connect backend.
+
+This will only work with keyless tasks.
+
+Config Keys
+===========
+
+The following common keys are supported:
+
+* :ref:`discover <conf_backend_common_discover>`
+* :ref:`discover_data <conf_backend_common_discover_data>`
+* :ref:`extra_metrics_tags <conf_backend_common_extra_metrics_tags>`
+
+tls_client
+----------
+
+**optional**, **type**: :ref:`rustls client config <conf_value_rustls_client_config>`
+
+Enable TLS and set TLS parameters for this local TLS client.
+
+**default**: not set
+
+tls_name
+--------
+
+**optional**, **type**: :ref:`tls name <conf_value_tls_name>`
+
+Set the tls server name to verify tls certificate for all peers.
+
+If not set, the peer IP will be used.
+
+**default**: not set
+
+duration_stats
+--------------
+
+**optional**, **type**: :ref:`histogram metrics <conf_value_histogram_metrics>`
+
+Histogram metrics config for the tcp connect duration stats.
+
+**default**: set with default value
+
+request_buffer_size
+-------------------
+
+**optional**, **type**: usize
+
+Set the request buffer size of the local queue. New connections will be opened when the queue is full.
+
+**default**: 128
+
+response_timeout
+----------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the timeout value for the waiting of the response.
+
+If timeout, the request will be dropped for the local buffer and an internal error response will be send to client.
+
+**default**: 4s
+
+graceful_close_wait
+-------------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the graceful wait time duration before we close an alive connection.
+
+**default**: 10s
+
+idle_connection_min
+-------------------
+
+**optional**, **type**: usize
+
+Set the minimum number of IDLE connections in the pool.
+
+**default**: 128
+
+idle_connection_max
+-------------------
+
+**optional**, **type**: usize
+
+Set the maximum number of IDLE connections in the pool.
+
+**default**: 4096
+
+tcp_keepalive
+-------------
+
+**optional**, **type**: :ref:`tcp keepalive <conf_value_tcp_keepalive>`
+
+Set tcp keepalive.
+
+**default**: no keepalive set

g3tiles/doc/configuration/backends/stream_tcp.rst

@@ -0,0 +1,38 @@
+.. _configuration_backend_stream_tcp:
+
+**********
+stream_tcp
+**********
+
+A layer-4 tcp connect backend.
+
+This will only work with stream tasks.
+
+Config Keys
+===========
+
+The following common keys are supported:
+
+* :ref:`discover <conf_backend_common_discover>`
+* :ref:`discover_data <conf_backend_common_discover_data>`
+* :ref:`extra_metrics_tags <conf_backend_common_extra_metrics_tags>`
+
+peer_pick_policy
+----------------
+
+**optional**, **type**: :ref:`selective pick policy <conf_value_selective_pick_policy>`
+
+Set the policy to select next peer address.
+
+The key for ketama/rendezvous/jump hash is *<client-ip>*.
+
+**default**: random
+
+duration_stats
+--------------
+
+**optional**, **type**: :ref:`histogram metrics <conf_value_histogram_metrics>`
+
+Histogram metrics config for the tcp connect duration stats.
+
+**default**: set with default value

g3tiles/doc/configuration/discovers/host_resolver.rst

@@ -0,0 +1,18 @@
+.. _configuration_discover_host_resolver:
+
+host_resolver
+=============
+
+This is the host resolver discover designed to resolve IP addresses via the host resolver.
+
+Config Keys
+-----------
+
+There are no extra config keys for this kind of discover.
+
+.. _conf_discover_host_resolver_register_data:
+
+Register Data
+-------------
+
+The data should be a :ref:`upstream str <conf_value_upstream_str>` value, and the *port* field is required.

g3tiles/doc/configuration/discovers/index.rst

@@ -0,0 +1,53 @@
+.. _configuration_discover:
+
+********
+Discover
+********
+
+The type for each discover config is *map*, with two always required keys:
+
+* :ref:`name <conf_discover_common_name>`, which specify the name of the server.
+* :ref:`type <conf_discover_common_type>`, which specify the real type of the discover, decides how to parse other keys.
+
+There are many types of discover, each with a section below.
+
+Discovers
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   static_addr
+   host_resolver
+
+Common Keys
+===========
+
+This section describes the common keys, they may be used by many discovers.
+
+.. _conf_discover_common_name:
+
+**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+
+Set the name of the discover.
+
+.. _conf_discover_common_type:
+
+**required**, **type**: str
+
+Set the type of the discover.
+
+.. _conf_discover_register_data:
+
+Register Data
+=============
+
+Each discover will have it's own format for the register data. Follow the link bellow to see more details.
+
++--------------+----------------------------------------------------------------------+
+|Type          |Link                                                                  |
++==============+======================================================================+
+|static_addr   |:ref:`static_addr data <conf_discover_static_addr_register_data>`     |
++--------------+----------------------------------------------------------------------+
+|host_resolver |:ref:`host_resolver data <conf_discover_host_resolver_register_data>` |
++--------------+----------------------------------------------------------------------+

g3tiles/doc/configuration/discovers/static_addr.rst

@@ -0,0 +1,19 @@
+.. _configuration_discover_static_addr:
+
+static_addr
+===========
+
+This is the static addr discover designed to parse static addresses.
+
+Config Keys
+-----------
+
+There are no extra config keys for this kind of discover.
+
+.. _conf_discover_static_addr_register_data:
+
+Register Data
+-------------
+
+The data should be a :ref:`weighted sockaddr <conf_value_weighted_sockaddr>` or
+a sequence of :ref:`weighted sockaddr <conf_value_weighted_sockaddr>` value.

g3tiles/doc/configuration/index.rst

@@ -0,0 +1,45 @@
+.. _configuration:
+
+#############
+Configuration
+#############
+
+YAML is used as the configuration file format. The main conf file,
+which should be specified with the command line option *-c*,
+is make up of the following entries:
+
++-----------+----------+-------+------------------------------------------------+
+|Key        |Type      |Reload |Description                                     |
++===========+==========+=======+================================================+
+|runtime    |Map       |no     |Runtime config, see :doc:`runtime`              |
++-----------+----------+-------+------------------------------------------------+
+|worker     |Map [#w]_ |no     |An unaided runtime will be started if present.  |
++-----------+----------+-------+------------------------------------------------+
+|log        |Map       |no     |Log config, see :doc:`log/index`                |
++-----------+----------+-------+------------------------------------------------+
+|stat       |Map       |no     |Stat config, see :doc:`stat`                    |
++-----------+----------+-------+------------------------------------------------+
+|controller |Seq       |no     |Controller config                               |
++-----------+----------+-------+------------------------------------------------+
+|discover   |Mix [#m]_ |yes    |Discover config                                 |
++-----------+----------+-------+------------------------------------------------+
+|backend    |Mix [#m]_ |yes    |Backend config                                  |
++-----------+----------+-------+------------------------------------------------+
+|server     |Mix [#m]_ |yes    |Server config, see :doc:`servers/index`         |
++-----------+----------+-------+------------------------------------------------+
+
+.. rubric:: Footnotes
+
+.. [#m] *Mix* is not a yaml type, see :ref:`hybrid map <conf_value_hybrid_map>` for the real format.
+.. [#w] See :ref:`unaided runtime config <conf_value_unaided_runtime_config>`.
+
+.. toctree::
+   :hidden:
+
+   values/index
+   runtime
+   log/index
+   stat
+   discovers/index
+   backends/index
+   servers/index

g3tiles/doc/configuration/log/driver/fluentd.rst

@@ -0,0 +1,147 @@
+.. _configuration_log_driver_fluentd:
+
+fluentd
+=======
+
+The fluentd driver config is is map format.
+
+We can set it to send logs to fluentd / fluent-bit by using it's `Forward Protocol`_.
+
+.. _Forward Protocol: https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1
+
+The tags in the fluentd event message will be g3tiles.Task for the corresponding logs.
+
+The keys are described below.
+
+address
+-------
+
+**optional**, **type**: :ref:`env sockaddr str <conf_value_env_sockaddr_str>`
+
+Set the tcp address of the fluentd server.
+
+**default**: 127.0.0.1:24224
+
+bind_ip
+-------
+
+**optional**, **type**: :ref:`ip addr str <conf_value_ip_addr_str>`
+
+Set the ip address to bind to for the local socket.
+
+**default**: not set
+
+shared_key
+----------
+
+**optional**, **type**: str
+
+Set the shared key if authentication is required.
+
+The handshake stage will be skipped if shared key is not set.
+
+**default**: not set
+
+username
+--------
+
+**optional**, **type**: str
+
+Set the username if authorization is required.
+
+This will only be used if authorization is required by the server.
+
+**default**: not set
+
+password
+--------
+
+**optional**, **type**: str
+
+Set the password if authorization is required.
+
+This will only be used if authorization is required by the server.
+
+**default**: not set
+
+hostname
+--------
+
+**optional**, **type**: str
+
+Set a custom hostname.
+
+**default**: local hostname
+
+tcp_keepalive
+-------------
+
+**optional**, **type**: :ref:`tcp keepalive <conf_value_tcp_keepalive>`
+
+Set the tcp keepalive config for the connection to fluentd server.
+
+**default**: enabled with system default values
+
+tls_client
+----------
+
+**optional**, **type**: :ref:`rustls client config <conf_value_rustls_client_config>`
+
+Enable tls and set the config.
+
+**default**: not set
+
+tls_name
+--------
+
+**optional**, **type**: :ref:`tls name <conf_value_tls_name>`
+
+Set the tls server name to verify peer certificate.
+
+**default**: not set
+
+connect_timeout
+---------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the timeout value for the connection to fluentd server, including tcp connect, tls handshake, fluentd handshake.
+
+**default**: 10s
+
+connect_delay
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the delay time if the connect to fluentd server failed. All messages received will be dropped during this stage.
+
+**default**: 10s
+
+write_timeout
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the write timeout for each message. The message will be dropped if timeout.
+
+default: 1s
+
+flush_interval
+--------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the flush interval for the connection to fluentd server.
+
+**default**: 100ms
+
+retry_queue_len
+---------------
+
+**optional**, **type**: usize
+
+Set how many events will be queued up to retry when connect or write failed.
+Note the write timeout events will be dropped directly.
+
+**default**: 10

g3tiles/doc/configuration/log/driver/index.rst

@@ -0,0 +1,20 @@
+.. _configuration_log_driver:
+
+**********
+Log Driver
+**********
+
+We support the following log drivers:
+
+* journald
+
+* syslog
+
+* fluentd
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Details:
+
+   syslog
+   fluentd

g3tiles/doc/configuration/log/driver/syslog.rst

@@ -0,0 +1,155 @@
+.. _configuration_log_driver_syslog:
+
+syslog
+======
+
+The syslog driver config is is map format.
+
+We can set it to send logs to syslogd, which can be listening on
+
+ * unix socket, which is default
+ * udp socket
+
+The message format can be
+
+ * rfc3164, which is default
+ * rfc5424
+
+The keys are described below.
+
+target_unix
+-----------
+
+**optional**, **type**: mix
+
+You can set this if you want to send syslog to a custom unix socket path.
+
+The value can be a map, with the following keys:
+
+* path
+
+  **required**, **type**: :ref:`absolute path <conf_value_absolute_path>`
+
+  The syslogd daemon listen socket path.
+
+If the value type is str, the value should be the same as the value as *path* above.
+
+**default**: not set
+
+target_udp
+----------
+
+**optional**, **type**: mix
+
+You can set this if you want to send syslog to a remote syslogd which listening on a udp socket.
+
+The value can be a map, with the following keys:
+
+* address
+
+  **required**, **type**: :ref:`env sockaddr str <conf_value_env_sockaddr_str>`
+
+  Set the remote socket address.
+
+* bind_ip
+
+  **optional**, **type**: :ref:`ip addr str <conf_value_ip_addr_str>`
+
+  Set the ip address to bind to for the local socket.
+
+  **default**: not set
+
+If the value type is str, the value should be the same as the value as *address* above.
+
+**default**: not set
+
+target
+------
+
+**optional**, **type**: map
+
+This is just another form to set syslog target address.
+
+The key *udp* is just handled as *target_udp* as above.
+
+The key *unix* is just handled as *target_unix* as above.
+
+format_rfc5424
+--------------
+
+**optional**, **type**: mix
+
+Set this to use rfc5424 message format.
+
+The value can be a map, with the following keys:
+
+* enterprise_id
+
+  **optional**, **type**: int
+
+  Set the enterprise id value as described in `rfc5424`_.
+
+  See `PRIVATE ENTERPRISE NUMBERS`_ for IANA allocated numbers.
+
+  **default**: 0, which is reserved
+
+  .. _rfc5424: https://tools.ietf.org/html/rfc5424
+  .. _PRIVATE ENTERPRISE NUMBERS: https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers
+
+* message_id
+
+  **optional**, **type**: str
+
+  Set the message id.
+
+  **default**: not set
+
+If the value type is int, the value should be the same as the value as *enterprise_id* above.
+If the value type is str, the value should be the same as the value as *message_id* above.
+
+**default**: not set
+
+use_cee_log_syntax
+------------------
+
+**optional**, **type**: bool
+
+Set if we should use `CEE Log Syntax`_.
+
+Enable this option if you need to use rsyslog `mmjsonparse`_ module.
+
+**default**: not set
+
+.. _mmjsonparse: https://www.rsyslog.com/files/temp/doc-indent/configuration/modules/mmjsonparse.html
+.. _CEE Log Syntax: https://cee.mitre.org/language/1.0-beta1/cls.html
+
+cee_event_flag
+--------------
+
+**optional**, **type**: ascii string
+
+Set a custom CEE event flag value. Only meaningful if *use_cee_log_syntax* is set.
+
+The one defined by `CLT`_ is *@cee:*, you can override it by using this option.
+
+**default**: @cee:
+
+.. _CLT: https://cee.mitre.org/language/1.0-beta1/clt.html
+
+emit_hostname
+-------------
+
+**optional**, **type**: bool
+
+Set if we should set hostname in the syslog message header.
+
+**default**: false
+
+append_report_ts
+----------------
+
+**optional**, **type**: bool
+
+Set if we should add :ref:`report_ts <log_shared_keys_report_ts>` to logs.
+
+**default**: false

g3tiles/doc/configuration/log/index.rst

@@ -0,0 +1,101 @@
+.. _configuration_log:
+
+***
+Log
+***
+
+This is the initial *log* config, which is optional and can not be reloaded.
+If set, it must reside in the main conf file.
+
+Root Value
+==========
+
+The value could be a simple string, which is the driver name, such as
+
+- discard
+
+  drop the logs. This is the **default**.
+
+- journal
+
+  send logs to journald directly.
+
+- syslog
+
+  send logs to syslogd directly.
+
+In such case, a default driver is used as default log config for all loggers.
+
+The value could be a map, with the following keys:
+
+- default
+
+  **optional**, **type**: :ref:`log config <configuration_log_config>`
+
+  Set default log config for loggers with no explicit config.
+
+  **default**: journal log config
+
+- task
+
+  **optional**, **type**: :ref:`log config <configuration_log_config>`
+
+  Set log config for *task* loggers.
+
+  **default**: not set
+
+.. _configuration_log_config:
+
+log config
+==========
+
+The detailed log config may be a simple driver name, or a map, with the following keys:
+
+- journal
+
+  **optional**, **type**: map
+
+  Use *journal* log driver. An empty map should be used, as no keys are defined by now.
+
+- syslog
+
+  **optional**, **type**: :ref:`syslog <configuration_log_driver_syslog>`
+
+  Use *syslog* log driver.
+
+- async_channel_size
+
+  **optional**, **type**: usize
+
+  Set the internal async channel size.
+
+  **default**: 4096
+
+- async_thread_number
+
+  **optional**, **type**: usize
+
+  Set the number of async threads.
+
+  This has no effect on *discard* and *journal* log driver.
+
+  **default**: 1
+
+- io_error_sampling_offset
+
+  **optional**, **type**: usize, **max**: 16
+
+  The logger may encounter io error, we should report it anyhow. We will log this error every *2^n* times,
+  where *n* can be set here.
+
+  This has no effect on *discard* and *journal* log driver.
+
+  **default**: 10
+
+.. note:: The *discard* driver has no config options, so it doesn't has a corresponding map field.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: More:
+
+   driver/index

g3tiles/doc/configuration/runtime.rst

@@ -0,0 +1,103 @@
+.. _configuration_runtime:
+
+*******
+Runtime
+*******
+
+This is the *runtime* config, which is optional. If set, it must reside in the main conf file.
+
+All the options in this config are optional with a reasonable default value.
+Set them only if you really known their meaning.
+
+The options can be grouped into the following sections:
+
+tokio main runtime
+==================
+
+This section describes the options for the main tokio runtime, which is used for all servers.
+
+thread_number
+-------------
+
+**optional**, **type**: int | str
+
+Set the scheduler and core number of worker threads.
+
+if *0*, a basic scheduler is used.
+if not *0*, a threaded scheduler with the specified number of worker thread is used.
+
+**default**: threaded scheduler with worker threads on each all available CPU core.
+
+thread_name
+-----------
+
+**optional**, **type**: str
+
+Set name of worker threads spawned. Only ASCII characters is allowed.
+Note that the length of thread name will be restricted at the OS level.
+
+**default**: "tokio"
+
+thread_stack_size
+-----------------
+
+**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+Set the stack size for worker threads. For *<int>* value, the unit is bytes.
+
+**default**: `tokio thread_stack_size`_
+
+.. _tokio thread_stack_size: https://docs.rs/tokio/0.2.21/tokio/runtime/struct.Builder.html#method.thread_stack_size
+
+max_io_events_per_tick
+----------------------
+
+**optional**, **type**: usize
+
+Configures the max number of events to be processed per tick.
+
+**default**: 1024, tokio default value
+
+daemon quit control
+===================
+
+This section describes the options used during graceful quit of the daemon.
+
+server_offline_delay
+--------------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the time duration before offline all servers after received daemon quit signals.
+All listen server sockets will be closed after this duration, so it should be more than the time used to
+start the new daemon process if you depends on it for graceful restart.
+
+**default**: 8s
+
+task_wait_delay
+---------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the time duration before checking alive tasks after all servers going into offline mode.
+Tasks are marked as alive only if auth success, so we should leave some time for those tasks in negotiation
+state to run into their next state, which may be alive or really dead.
+
+**default**: 2s
+
+task_wait_timeout
+-----------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the time duration before force quit alive tasks after we decide to wait for them to end gracefully.
+
+**default**: 10h
+
+task_quit_timeout
+-----------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the time duration before we shutdown the process after entering force quit status for all tasks.
+The tasks dropped after this timeout won't have any logs.

g3tiles/doc/configuration/servers/dummy_close.rst

@@ -0,0 +1,8 @@
+.. _configuration_server_dummy_close:
+
+dummy_close
+===========
+
+This is the dummy server designed to close all connections.
+
+There are no extra config keys for this kind of server.

g3tiles/doc/configuration/servers/index.rst

@@ -0,0 +1,180 @@
+.. _configuration_server:
+
+******
+Server
+******
+
+The type for each server config is *map*, with two always required keys:
+
+* :ref:`name <conf_server_common_name>`, which specify the name of the server.
+* :ref:`type <conf_server_common_type>`, which specify the real type of the server, decides how to parse other keys.
+
+There are many types of server, each with a section below.
+
+Servers
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   dummy_close
+   openssl_proxy
+   rustls_proxy
+   keyless_proxy
+   plain_tcp_port
+   plain_quic_port
+
+Common Keys
+===========
+
+This section describes the common keys, they may be used by many servers.
+
+.. _conf_server_common_name:
+
+**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+
+Set the name of the server.
+
+.. _conf_server_common_type:
+
+**required**, **type**: str
+
+Set the type of the server.
+
+.. _conf_server_common_shared_logger:
+
+shared_logger
+-------------
+
+**optional**, **type**: ascii
+
+Set the server to use a logger running on a shared thread.
+
+**default**: not set
+
+.. _conf_server_common_listen_in_worker:
+
+listen_in_worker
+----------------
+
+**optional**, **type**: bool
+
+Set if we should listen in each worker runtime if you have worker enabled.
+
+The listen instance count will be the same with the worker number count.
+
+**default**: false
+
+.. _conf_server_common_ingress_network_filter:
+
+ingress_network_filter
+----------------------
+
+**optional**, **type**: :ref:`ingress network acl rule <conf_value_ingress_network_acl_rule>`
+
+Set the network filter for clients.
+
+The used client address will always be the interpreted client address, which means it will be the raw socket peer addr
+for servers that listen directly, and it will be the address set in the PROXY Protocol message for serverw chained after
+the server that support PROXY Protocol.
+
+**default**: not set
+
+.. _conf_server_common_tcp_sock_speed_limit:
+
+tcp_sock_speed_limit
+--------------------
+
+**optional**, **type**: :ref:`tcp socket speed limit <conf_value_tcp_sock_speed_limit>`
+
+Set speed limit for each tcp socket.
+
+**default**: no limit
+
+.. _conf_server_common_udp_sock_speed_limit:
+
+udp_sock_speed_limit
+--------------------
+
+**optional**, **type**: :ref:`udp socket speed limit <conf_value_udp_sock_speed_limit>`
+
+Set speed limit for each udp socket.
+
+**default**: no limit
+
+.. _conf_server_common_tcp_copy_buffer_size:
+
+tcp_copy_buffer_size
+--------------------
+
+**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+Set the buffer size for internal tcp copy.
+
+**default**: 16K, **minimal**: 4K
+
+.. _conf_server_common_tcp_copy_yield_size:
+
+tcp_copy_yield_size
+-------------------
+
+**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+Set the yield out size for the internal copy task.
+
+**default**: 1M, **minimal**: 256K
+
+.. _conf_server_common_tcp_misc_opts:
+
+tcp_misc_opts
+-------------
+
+**optional**, **type**: :ref:`tcp misc sock opts <conf_value_tcp_misc_sock_opts>`
+
+Set misc tcp socket options on accepted tcp sockets.
+
+**default**: not set, nodelay is default enabled
+
+.. _conf_server_common_udp_misc_opts:
+
+udp_misc_opts
+-------------
+
+**optional**, **type**: :ref:`udp misc sock opts <conf_value_udp_misc_sock_opts>`
+
+Set misc udp socket options on created udp sockets.
+
+**default**: not set
+
+.. _conf_server_common_task_idle_check_duration:
+
+task_idle_check_duration
+------------------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the idle check duration for task.
+
+**default**: 5min, **max**: 30min
+
+.. _conf_server_common_task_idle_max_count:
+
+task_idle_max_count
+-------------------
+
+**optional**, **type**: i32
+
+The task will be closed if the idle check return IDLE the times as this value.
+
+**default**: 1
+
+.. _conf_server_common_extra_metrics_tags:
+
+extra_metrics_tags
+------------------
+
+**optional**, **type**: :ref:`static metrics tags <conf_value_static_metrics_tags>`
+
+Set extra metrics tags that should be added to server stats and user stats already with server tags added.
+
+**default**: not set

g3tiles/doc/configuration/servers/keyless_proxy.rst

@@ -0,0 +1,30 @@
+.. _configuration_server_keyless_proxy:
+
+keyless_proxy
+=============
+
+A keyless reverse proxy server.
+
+The following common keys are supported:
+
+* :ref:`shared_logger <conf_server_common_shared_logger>`
+* :ref:`ingress_network_filter <conf_server_common_ingress_network_filter>`
+* :ref:`task_idle_check_duration <conf_server_common_task_idle_check_duration>`
+* :ref:`task_idle_max_count <conf_server_common_task_idle_max_count>`
+* :ref:`extra_metrics_tags <conf_server_common_extra_metrics_tags>`
+
+backend
+-------
+
+**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+
+Set the backend name.
+
+spawn_task_unconstrained
+------------------------
+
+**optional**, **type**: bool
+
+Set if we should spawn tasks in tokio unconstrained way.
+
+**default**: false

g3tiles/doc/configuration/servers/openssl_proxy.rst

@@ -0,0 +1,198 @@
+.. _configuration_server_openssl_proxy:
+
+openssl_proxy
+=============
+
+A layer-4 TLS reverse proxy server based on Rustls.
+
+The following common keys are supported:
+
+* :ref:`shared_logger <conf_server_common_shared_logger>`
+* :ref:`listen_in_worker <conf_server_common_listen_in_worker>`
+* :ref:`tcp_sock_speed_limit <conf_server_common_tcp_sock_speed_limit>`
+* :ref:`ingress_network_filter <conf_server_common_ingress_network_filter>`
+* :ref:`tcp_copy_buffer_size <conf_server_common_tcp_copy_buffer_size>`
+* :ref:`tcp_copy_yield_size <conf_server_common_tcp_copy_yield_size>`
+* :ref:`tcp_misc_opts <conf_server_common_tcp_misc_opts>`
+* :ref:`task_idle_check_duration <conf_server_common_task_idle_check_duration>`
+* :ref:`task_idle_max_count <conf_server_common_task_idle_max_count>`
+* :ref:`extra_metrics_tags <conf_server_common_extra_metrics_tags>`
+
+listen
+------
+
+**optional**, **type**: :ref:`tcp listen <conf_value_tcp_listen>`
+
+Set the listen config for this server.
+
+The instance count setting will be ignored if *listen_in_worker* is correctly enabled.
+
+**default**: not set
+
+client_hello_recv_timeout
+-------------------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the timeout value for the wait of initial client hello data.
+
+**default**: 10s
+
+accept_timeout
+--------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the timeout value for the accept of the full TLS handshake.
+
+**default**: 60s
+
+spawn_task_unconstrained
+------------------------
+
+**optional**, **type**: bool
+
+Set if we should spawn tasks in tokio unconstrained way.
+
+**default**: false
+
+alert_unrecognized_name
+-----------------------
+
+**optional**, **type**: bool
+
+Set if we should send TLS alert when no host config can be recognized.
+
+**default**: false
+
+virtual_hosts
+-------------
+
+**required**, **type**: :ref:`host matched object <conf_value_host_matched_object>` <:ref:`host <configuration_server_openssl_proxy_host>`>
+
+Set the list of hosts we should handle based on host match rules.
+
+If not set, all requests will be handled.
+
+Example:
+
+.. code-block:: yaml
+
+  hosts:
+    name: bench
+    exact_match: bench.example.net
+    cert_pairs:
+      certificate: bench.example.net-ec256.crt
+      private_key: bench.example.net-ec256.key
+    backends:
+      - http
+
+**default**: not set
+
+.. _configuration_server_openssl_proxy_host:
+
+Host
+^^^^
+
+This set the config for a OpenSSl virtual host.
+
+name
+""""
+
+**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+
+Set the name of this virtual host.
+
+**default**: not set
+
+cert_pairs
+""""""""""
+
+**optional**, **type**: :ref:`tls cert pair <conf_value_tls_cert_pair>` or seq
+
+Set certificate and private key pairs for this TLS server.
+
+If not set, TLS protocol will be disabled.
+
+**default**: not set
+
+tlcp_cert_pairs
+"""""""""""""""
+
+**optional**, **type**: :ref:`tlcp cert pair <conf_value_tlcp_cert_pair>` or seq
+
+Set certificate and private key pairs for this TLCP server.
+
+If not set, TLCP protocol will be disabled.
+
+enable_client_auth
+""""""""""""""""""
+
+**optional**, **type**: bool
+
+Set if you want to enable client auth.
+
+**default**: disabled
+
+session_id_context
+""""""""""""""""""
+
+**optional**, **type**: str
+
+A string that will be added to the prefix when calculate the session id context sha1 hash.
+
+**default**: not set
+
+ca_certificate
+""""""""""""""
+
+**optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
+
+A list of certificates for client auth. If not set, the system default ca certificates will be used.
+
+**default**: not set
+
+request_rate_limit
+""""""""""""""""""
+
+**optional**, **type**: :ref:`rate limit quota <conf_value_rate_limit_quota>`
+
+Set rate limit on request.
+
+**default**: no limit
+
+request_max_alive
+"""""""""""""""""
+
+**optional**, **type**: usize, **alias**: request_alive_max
+
+Set max alive requests at virtual host level.
+
+Even if not set, the max alive requests should not be more than usize::MAX.
+
+**default**: no limit
+
+tcp_sock_speed_limit
+""""""""""""""""""""
+
+**optional**, **type**: :ref:`tcp socket speed limit <conf_value_tcp_sock_speed_limit>`
+
+Set speed limit for each tcp socket.
+
+This will overwrite the server level :ref:`tcp_sock_speed_limit <conf_server_common_tcp_sock_speed_limit>`.
+
+**default**: no set
+
+task_idle_max_count
+"""""""""""""""""""
+
+**optional**, **type**: i32
+
+The task will be closed if the idle check return IDLE the times as this value.
+
+This will overwrite the server level :ref:`task_idle_max_count <conf_server_common_task_idle_max_count>`.
+
+**default**: not set
+
+backends
+""""""""

g3tiles/doc/configuration/servers/plain_quic_port.rst

@@ -0,0 +1,47 @@
+.. _configuration_server_plain_quic_port:
+
+plain_quic_port
+===============
+
+This server provides plain quic port, which can be placed in front of other servers.
+
+The following common keys are supported:
+
+* :ref:`listen_in_worker <conf_server_common_listen_in_worker>`
+* :ref:`ingress_network_filter <conf_server_common_ingress_network_filter>`
+
+listen
+------
+
+**required**, **type**: :ref:`udp listen <conf_value_udp_listen>`
+
+Set the udp listen config for this server.
+
+The instance count setting will be ignored if *listen_in_worker* is correctly enabled.
+
+quic_server
+-----------
+
+**required**, **type**: :ref:`rustls server config <conf_value_rustls_server_config>`
+
+Set the crypto config for this quic server.
+
+offline_rebind_port
+-------------------
+
+**optional**, **type**: u16
+
+Set a rebind port if you want graceful shutdown.
+
+The new port should be reachable from the client or it won't work as expected.
+
+**default**: not set
+
+server
+------
+
+**required**, **type**: str
+
+Set name of the next server to send the accepted connections to.
+
+The next server should be able to accept tcp connections.

g3tiles/doc/configuration/servers/plain_tcp_port.rst

@@ -0,0 +1,51 @@
+.. _configuration_server_plain_tcp_port:
+
+plain_tcp_port
+==============
+
+This server provides plain tcp port, which can be placed in front of other servers.
+
+The following common keys are supported:
+
+* :ref:`listen_in_worker <conf_server_common_listen_in_worker>`
+* :ref:`ingress_network_filter <conf_server_common_ingress_network_filter>`
+
+listen
+------
+
+**required**, **type**: :ref:`tcp listen <conf_value_tcp_listen>`
+
+Set the listen config for this server.
+
+The instance count setting will be ignored if *listen_in_worker* is correctly enabled.
+
+server
+------
+
+**required**, **type**: str
+
+Set name of the next server to send the accepted connections to.
+
+The next server should be able to accept tcp connections.
+
+proxy_protocol
+--------------
+
+**optional**, **type**: :ref:`proxy protocol version <conf_value_proxy_protocol_version>`
+
+Set the version of PROXY protocol we use for incoming tcp connections.
+
+If set, connections with no matched PROXY Protocol message will be dropped.
+
+.. note:: The *ingress_network_filter* config option of this server will always applies to the real socket client address.
+
+**default**: not set, which means PROXY protocol won't be used
+
+proxy_protocol_read_timeout
+---------------------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the timeout value before we read a complete PROXY Protocol message.
+
+**default**: 5s

g3tiles/doc/configuration/servers/rustls_proxy.rst

@@ -0,0 +1,180 @@
+.. _configuration_server_rustls_proxy:
+
+rustls_proxy
+============
+
+A layer-4 TLS reverse proxy server based on OpenSSL or it's variants.
+
+The following common keys are supported:
+
+* :ref:`shared_logger <conf_server_common_shared_logger>`
+* :ref:`listen_in_worker <conf_server_common_listen_in_worker>`
+* :ref:`tcp_sock_speed_limit <conf_server_common_tcp_sock_speed_limit>`
+* :ref:`ingress_network_filter <conf_server_common_ingress_network_filter>`
+* :ref:`tcp_copy_buffer_size <conf_server_common_tcp_copy_buffer_size>`
+* :ref:`tcp_copy_yield_size <conf_server_common_tcp_copy_yield_size>`
+* :ref:`tcp_misc_opts <conf_server_common_tcp_misc_opts>`
+* :ref:`task_idle_check_duration <conf_server_common_task_idle_check_duration>`
+* :ref:`task_idle_max_count <conf_server_common_task_idle_max_count>`
+* :ref:`extra_metrics_tags <conf_server_common_extra_metrics_tags>`
+
+listen
+------
+
+**optional**, **type**: :ref:`tcp listen <conf_value_tcp_listen>`
+
+Set the listen config for this server.
+
+The instance count setting will be ignored if *listen_in_worker* is correctly enabled.
+
+**default**: not set
+
+client_hello_recv_timeout
+-------------------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the timeout value for the wait of initial client hello data.
+
+**default**: 10s
+
+spawn_task_unconstrained
+------------------------
+
+**optional**, **type**: bool
+
+Set if we should spawn tasks in tokio unconstrained way.
+
+**default**: false
+
+virtual_hosts
+-------------
+
+**required**, **type**: :ref:`host matched object <conf_value_host_matched_object>` <:ref:`host <configuration_server_rustls_proxy_host>`>
+
+Set the list of hosts we should handle based on host match rules.
+
+If not set, all requests will be handled.
+
+Example:
+
+.. code-block:: yaml
+
+  hosts:
+    name: bench
+    exact_match: bench.example.net
+    cert_pairs:
+      certificate: bench.example.net-ec256.crt
+      private_key: bench.example.net-ec256.key
+    backends:
+      - http
+
+**default**: not set
+
+.. _configuration_server_rustls_proxy_host:
+
+Host
+^^^^
+
+This set the config for a OpenSSl virtual host.
+
+name
+""""
+
+**required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+
+Set the name of this virtual host.
+
+**default**: not set
+
+cert_pairs
+""""""""""
+
+**optional**, **type**: :ref:`tls cert pair <conf_value_tls_cert_pair>` or seq
+
+Set certificate and private key pairs for this TLS server.
+
+If not set, TLS protocol will be disabled.
+
+**default**: not set
+
+enable_client_auth
+""""""""""""""""""
+
+**optional**, **type**: bool
+
+Set if you want to enable client auth.
+
+**default**: disabled
+
+use_session_ticket
+""""""""""""""""""
+
+**optional**, **type**: bool
+
+Set if we should enable TLS session ticket to do TLS Session Resumption without Server-Side State.
+
+**default**: disabled
+
+ca_certificate
+""""""""""""""
+
+**optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
+
+A list of certificates for client auth. If not set, the system default ca certificates will be used.
+
+**default**: not set
+
+accept_timeout
+""""""""""""""
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the timeout value for the accept of the full TLS handshake.
+
+**default**: 10s
+
+request_rate_limit
+""""""""""""""""""
+
+**optional**, **type**: :ref:`rate limit quota <conf_value_rate_limit_quota>`
+
+Set rate limit on request.
+
+**default**: no limit
+
+request_max_alive
+"""""""""""""""""
+
+**optional**, **type**: usize, **alias**: request_alive_max
+
+Set max alive requests at virtual host level.
+
+Even if not set, the max alive requests should not be more than usize::MAX.
+
+**default**: no limit
+
+tcp_sock_speed_limit
+""""""""""""""""""""
+
+**optional**, **type**: :ref:`tcp socket speed limit <conf_value_tcp_sock_speed_limit>`
+
+Set speed limit for each tcp socket.
+
+This will overwrite the server level :ref:`tcp_sock_speed_limit <conf_server_common_tcp_sock_speed_limit>`.
+
+**default**: no set
+
+task_idle_max_count
+"""""""""""""""""""
+
+**optional**, **type**: i32
+
+The task will be closed if the idle check return IDLE the times as this value.
+
+This will overwrite the server level :ref:`task_idle_max_count <conf_server_common_task_idle_max_count>`.
+
+**default**: not set
+
+backends
+""""""""

g3tiles/doc/configuration/stat.rst

@@ -0,0 +1,11 @@
+.. _configuration_stat:
+
+****
+Stat
+****
+
+This file described the stat config, which is optional and can not be reloaded.
+If set, it must reside in the main conf file.
+
+The value should be of type :ref:`statsd client config <conf_value_statsd_client_config>`,
+with the default *prefix* set to "g3tiles".

g3tiles/doc/configuration/values/acl.rst

@@ -0,0 +1,112 @@
+
+.. _configure_acl_value_types:
+
+***
+ACL
+***
+
+All acl value types are described here.
+
+Basic Type
+==========
+
+.. _conf_value_acl_action:
+
+acl action
+----------
+
+**yaml value**: str
+
+There are 4 types of acl actions:
+
+* permit
+
+  Permit if match the rule. Alternatives: allow, accept.
+
+* permit_log
+
+  Permit if match the rule and log. Alternatives: allow_log, accept_log.
+
+* forbid
+
+  Forbid if match the rule. Alternatives: deny, reject.
+
+* forbid_log
+
+  Forbid if match the rule and log. Alternatives: deny_log, reject_log.
+
+.. _conf_value_acl_rule:
+
+acl rule
+--------
+
+**yaml value**: mix
+
+All the rules share the same config format described in this section.
+
+An acl rule is consisted of many records, each of them has an associated :ref:`acl action <conf_value_acl_action>`.
+A default missed action can be set in the rule, it set the default action if no record matches.
+
+The value in map format is consisted of the following fields:
+
+* default
+
+  Set the default acl action if no rule match.
+
+  Default action if rule is set but with *default* omitted: forbid if not specified in the rule's doc.
+
+* any of the acl actions as the key str
+
+  The value should be a valid record or a list of them, with the key string as the acl action.
+  See detail types for the format of each record type.
+
+The value could also be a single record or a list of them, which means only them are permitted with no log.
+
+The default missed action is **forbid** and the default found action is **permit**,
+if they are not specified in the detail types.
+
+.. _conf_value_acl_rule_set:
+
+acl rule set
+------------
+
+**yaml value**: seq
+
+Acl rule set is a group of at least 2 acl rules. The rules are matched in order, see detail types for the real order.
+
+If any record in any rules is matched, that acl action will be used. If missed in all rules, all default missed actions
+will be compared and the most strict one will be used, so there is no default missed action at rule set level.
+
+Detail Type
+===========
+
+.. _conf_value_network_acl_rule:
+
+network acl rule
+----------------
+
+**yaml value**: :ref:`acl rule <conf_value_acl_rule>`
+
+The record type should be :ref:`ip network str <conf_value_ip_network_str>`.
+
+.. _conf_value_ingress_network_acl_rule:
+
+ingress network acl rule
+------------------------
+
+**yaml value**: :ref:`network acl rule <conf_value_network_acl_rule>`
+
+The same type as network acl rule. Default added: permit 127.0.0.1 and ::1.
+
+.. _conf_value_user_agent_acl_rule:
+
+user agent acl rule
+-------------------
+
+**yaml value**: :ref:`acl rule <conf_value_acl_rule>`
+
+The record type should be a valid **product** string as specified in `rfc7231 User-Agent`_.
+
+The default missed action is **permit** and the default found action is **forbid**.
+
+.. _rfc7231 User-Agent: https://tools.ietf.org/html/rfc7231#section-5.5.3

g3tiles/doc/configuration/values/base.rst

@@ -0,0 +1,182 @@
+
+.. _configure_base_value_types:
+
+****
+Base
+****
+
+.. _conf_value_env_var:
+
+env var
+=======
+
+**yaml value**: str
+
+Set a environment variable, in the form '$' + variable name, E.g. $TCP_LISTEN_ADDR.
+
+The value of the environment variable will be parsed just as you write this value as *yaml string* directly there.
+
+.. _conf_value_nonzero_u32:
+
+nonzero u32
+===========
+
+**yaml value**: int
+
+A non-zero u32 in value type.
+
+.. _conf_value_humanize_usize:
+
+humanize usize
+==============
+
+**yaml value**: int | str
+
+For *str* value, it support units of 2^10 like "KiB", "MiB", or units of 1000 like "KB", "MB".
+
+For *int* value or *str* value without unit, the unit will be bytes.
+
+.. seealso::
+
+   `humanize_rs bytes <https://docs.rs/humanize-rs/0.1.5/humanize_rs/bytes/index.html>`_
+
+.. _conf_value_humanize_u32:
+
+humanize u32
+============
+
+**yaml value**: int | str
+
+For *str* value, it support units of 2^10 like "KiB", "MiB", or units of 1000 like "KB", "MB".
+
+For *int* value or *str* value without unit, the unit will be bytes.
+
+.. _conf_value_humanize_duration:
+
+humanize duration
+=================
+
+**yaml value**: int | str
+
+For *str* value, at least one unit is required. Multiple units string like "1h 30m 71s" is also supported.
+See `duration units`_ for all supported units.
+
+For *int* and *real* value, the unit will be seconds.
+
+.. seealso::
+
+   `humanize_rs duration <https://docs.rs/humanize-rs/0.1.5/humanize_rs/duration/index.html>`_
+
+.. _duration units: https://docs.rs/humanize-rs/0.1.5/src/humanize_rs/duration/mod.rs.html#115
+
+.. _conf_value_upstream_str:
+
+upstream str
+============
+
+**yaml value**: str
+
+The string should be in *<ip>[:<port>]* or *<domain>[:<port>]* format.
+
+If omitted, the *port* will be set to *0*.
+
+.. _conf_value_url_str:
+
+url str
+=======
+
+**yaml value**: str
+
+The string should be a valid url.
+
+.. _conf_value_ascii_str:
+
+ascii str
+=========
+
+**yaml value**: str
+
+The string should only consists of ascii characters.
+
+.. _conf_value_rfc3339_datetime_str:
+
+rfc3339 datetime str
+====================
+
+**yaml value**: str
+
+The string should be a value rfc3339 datetime string.
+
+.. _conf_value_selective_pick_policy:
+
+selective pick policy
+=====================
+
+**yaml value**: str
+
+The policy to select item from selective vectors.
+
+The following values are supported:
+
+* random
+
+  The default one.
+
+* serial | sequence
+
+  For nodes with the same weights, the order is kept as in the config.
+
+* round_robin | rr
+
+  For nodes with the same weights, the order is kept as in the config.
+
+* ketama
+
+  Ketama Consistent Hash. The key format is defined in the context of each selective vector.
+
+* rendezvous
+
+  Rendezvous Hash. The key format is defined in the context of each selective vector.
+
+* jump_hash
+
+  Jump Consistent Hash. The key format is defined in the context of each selective vector.
+
+.. _conf_value_weighted_upstream_addr:
+
+weighted upstream addr
+======================
+
+**yaml value**: map | string
+
+A upstream str with weight set, which make can be grouped into selective vector.
+
+The map consists 2 fields:
+
+* addr
+
+  **required**, **type**: :ref:`upstream str <conf_value_upstream_str>`
+
+  The real value.
+
+* weight
+
+  **optional**, **type**: f64
+
+  The weight of the real value.
+  It may be converted to the smallest u32 greater than or equal to the f64 value when used.
+
+  **default**: 1.0
+
+If the value type is string, then it's value will be the *addr* field, with *weight* set to default value.
+
+.. _conf_value_list:
+
+list
+====
+
+**yaml value**: mix
+
+A list container type for type T.
+
+The value could be a single value of type T, or a sequence of values of type T.

g3tiles/doc/configuration/values/fs.rst

@@ -0,0 +1,71 @@
+
+.. _configure_fs_value_types:
+
+**********
+Filesystem
+**********
+
+.. _conf_value_hybrid_map:
+
+hybrid map
+==========
+
+**yaml value**: seq | str
+
+This is a hybrid container for a sequence of maps which may reside in other files.
+
+For *seq* value, all of it's values should be the final map, or a valid *str* value as described below.
+
+For *str* value, it should be a valid path, which may be absolute or relative to the directory of the main conf file.
+
+The path may be a file or directory:
+
+* If the path is a directory, the non-symbolic files in it with extension *.conf* will be parsed as described below.
+* If the path is a file, it should contains one or many yaml docs, each doc will be the final map.
+
+.. _conf_value_file_path:
+
+file path
+=========
+
+**yaml value**: str
+
+This set the path for a regular file to be used.
+
+The file should be an absolute path, or relative to a predefined path.
+
+The path should be existed, or can be auto created, according to the specific config.
+
+.. _conf_value_file:
+
+file
+====
+
+**yaml value**: str
+
+This set a file to be read. The file should be an absolute path, or relative to a predefined path.
+
+.. _conf_value_absolute_path:
+
+absolute path
+=============
+
+**yaml value**: str
+
+The set a file path to be used. The path should be absolute.
+
+.. _conf_value_config_file_format:
+
+config file format
+==================
+
+**yaml value**: str
+
+Set the format for the related config file.
+
+The following values are supported:
+
+* yaml
+* json
+
+The default vary in different contexts.

g3tiles/doc/configuration/values/index.rst

@@ -0,0 +1,19 @@
+
+******************
+Common Value Types
+******************
+
+There are many common values used across this document.
+The meanings and formats of them are described as follows:
+
+.. toctree::
+
+   base
+   fs
+   network
+   acl
+   tls
+   rate_limit
+   metrics
+   route
+   runtime

g3tiles/doc/configuration/values/metrics.rst

@@ -0,0 +1,196 @@
+
+.. _configure_metrics_value_types:
+
+*******
+Metrics
+*******
+
+.. _conf_value_metrics_value:
+
+metrics value
+=============
+
+**yaml value**: limited str
+
+Only the following characters are allowed:
+
+a to z, A to Z, 0 to 9, -, _, ., / or Unicode letters (as per the specification)
+
+The character range is the same as `OpenTSDB metrics-and-tags`_.
+
+.. _OpenTSDB metrics-and-tags: http://opentsdb.net/docs/build/html/user_guide/writing/index.html#metrics-and-tags
+
+.. _conf_value_static_metrics_tags:
+
+static metrics tags
+===================
+
+**yaml value**: map
+
+This should be a map, each key will be the tag name, and it's value will be the tag value.
+
+The tag name and the tag value should be of type :ref:`metrics value <conf_value_metrics_value>`.
+
+.. _conf_value_metrics_name:
+
+metrics name
+============
+
+**yaml value**: :ref:`metrics value <conf_value_metrics_value>`
+
+The metrics name
+
+.. _conf_value_weighted_metrics_name:
+
+weighted metrics name
+=====================
+
+**yaml value**: map | :ref:`metrics name <conf_value_metrics_name>`
+
+A metrics name with weight set, which make can be grouped into selective vector.
+
+The map consists 2 fields:
+
+* name
+
+  **required**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+
+  The name. The meaning of the name is depending on the config context.
+
+* weight
+
+  **optional**, **type**: f64
+
+  The weight of the name.
+  It may be converted to the smallest u32 greater than or equal to the f64 value when used.
+
+  **default**: 1.0
+
+If the value type is string, then it's value will be the *name* field, with *weight* set to default value.
+
+.. _conf_value_metrics_quantile:
+
+metrics quantile
+================
+
+**yaml value**: str | float
+
+A quantile value, should be in range 0.0 - 1.0.
+
+It's string value will be used as the value of quantile tag. You should prefer to use str form if you want the tag value
+to be the same as you typed in the config file.
+
+.. _conf_value_histogram_metrics:
+
+histogram metrics
+=================
+
+**yaml value**: map | :ref:`rotate <conf_value_histogram_metrics_rotate>`
+
+Config histogram metrics, such as the quantiles and rotate interval.
+
+The keys are:
+
+quantile
+--------
+
+**optional**, **type**: seq
+
+Set quantile list.
+
+Should be a sequence of :ref:`metrics quantile <conf_value_metrics_quantile>` or a string of them delimited by ','.
+
+**default**: 0.50, 0.80, 0.90, 0.95, 0.99
+
+.. _conf_value_histogram_metrics_rotate:
+
+rotate
+------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the rotate interval.
+
+**default**: 4s
+
+.. _conf_value_statsd_client_config:
+
+Statsd Client Config
+====================
+
+The full format of the root value should be a map, with the following keys:
+
+target_unix
+-----------
+
+**optional**, **type**: mix
+
+You can set this if you want to send statsd metrics to a custom unix socket path.
+
+The value can be a map, with the following keys:
+
+* path
+
+  **required**, **type**: :ref:`absolute path <conf_value_absolute_path>`
+
+  The syslogd daemon listen socket path.
+
+If the value type is str, the value should be the same as the value as *path* above.
+
+**default**: not set
+
+target_udp
+----------
+
+**optional**, **type**: mix
+
+You can set this if you want to send statsd metrics to a remote statsd which listening on a udp socket.
+
+The value can be a map, with the following keys:
+
+* address
+
+  **optional**, **type**: :ref:`env sockaddr str <conf_value_env_sockaddr_str>`
+
+  Set the remote socket address.
+
+  **default**: 127.0.0.1:8125
+
+* bind_ip
+
+  **optional**, **type**: :ref:`ip addr str <conf_value_ip_addr_str>`
+
+  Set the ip address to bind to for the local socket.
+
+  **default**: not set
+
+If the value type is str, the value should be the same as the value as *address* above.
+
+target
+------
+
+**optional**, **type**: map
+
+This is just another form to set statsd target address.
+
+The key *udp* is just handled as *target_udp* as above.
+
+The key *unix* is just handled as *target_unix* as above.
+
+prefix
+------
+
+**optional**, **type**: :ref:`metrics name <conf_value_metrics_name>`
+
+Set the global prefix for all metrics.
+
+**default**: "g3tiles"
+
+emit_duration
+-------------
+
+**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+Set the emit duration for local stats. All stats will be send out in sequence.
+
+**default**: 200ms

g3tiles/doc/configuration/values/network.rst

@@ -0,0 +1,625 @@
+
+.. _configure_network_value_types:
+
+*******
+Network
+*******
+
+.. _conf_value_sockaddr_str:
+
+sockaddr str
+============
+
+**yaml value**: str
+
+The string should be in *<ip>[:<port>]* format, in which the port may be omitted if a default value is available.
+
+.. _conf_value_static_sockaddr_str:
+
+static sockaddr str
+===================
+
+**yaml value**: str
+
+The string should be in *@<domain>:<port>* or *@<ip>:<port>* format.
+
+It is different from :ref:`upstream str <conf_value_upstream_str>` as:
+
+- It will be resolved when we load the config files
+- The domain is only allowed to be resolved to just 1 IP address
+
+.. _conf_value_env_sockaddr_str:
+
+env sockaddr str
+================
+
+**yaml value**: :ref:`sockaddr str <conf_value_sockaddr_str>` or :ref:`static sockaddr str <conf_value_static_sockaddr_str>` or :ref:`env var <conf_value_env_var>`
+
+The string should be in *<ip>[:<port>]* format, in which the port may be omitted if a default value is available.
+
+.. _conf_value_ip_addr_str:
+
+ip addr str
+===========
+
+**yaml value**: str
+
+The string should be in *<ip>* format.
+
+.. _conf_value_ipv4_addr_str:
+
+ipv4 addr str
+=============
+
+**yaml value**: str
+
+The string should be in *<ipv4 address>* format.
+
+.. _conf_value_ipv6_addr_str:
+
+ipv6 addr str
+=============
+
+**yaml value**: str
+
+The string should be in *<ipv6 address>* format.
+
+Ipv4 mapped address should not be set when this type is required.
+
+.. _conf_value_ip_network_str:
+
+ip network str
+==============
+
+**yaml value**: str
+
+The string should be a network address in CIDR format, or just an ip address.
+
+.. _conf_value_host:
+
+host
+====
+
+**yaml value**: str
+
+A host value. Which should be either a valid domain, or a valid IP address.
+
+.. _conf_value_domain:
+
+domain
+======
+
+**yaml value**: str
+
+A domain value. The string value should be able to convert to a IDNA domain.
+
+Leading '.' is not allowed.
+
+.. _conf_value_weighted_sockaddr:
+
+weighted sockaddr
+=================
+
+**yaml value**: map | string
+
+A socket addr str with weight set, which make can be grouped into selective vector.
+
+The map consists 2 fields:
+
+* addr
+
+  **required**, **type**: :ref:`sockaddr str <conf_value_sockaddr_str>`
+
+  The real value.
+
+* weight
+
+  **optional**, **type**: f64
+
+  The weight of the real value.
+  It may be converted to the smallest u32 greater than or equal to the f64 value when used.
+
+  **default**: 1.0
+
+If the value type is string, then it's value will be the *addr* field, with *weight* set to default value.
+
+.. _conf_value_socket_buffer_config:
+
+socket buffer config
+====================
+
+**yaml value**: mix
+
+It consists of 2 fields:
+
+* recv
+
+  **optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+  Set the recv buf size.
+
+  **default**: not set
+
+* send
+
+  **optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+  Set the send buf size.
+
+  **default**: not set
+
+The yaml value for *socket buffer config* can be in the following formats:
+
+* int | string
+
+  The value will be set for both **recv** and **send** fields above.
+
+* map
+
+  The keys of this map are the fields as described above.
+
+.. _conf_value_tcp_listen:
+
+tcp listen
+==========
+
+**yaml value**: mix
+
+It consists of the following fields:
+
+* address
+
+  **required**, **type**: :ref:`env sockaddr str <conf_value_env_sockaddr_str>`
+
+  Set the listen socket address.
+
+  **default**: [::]:0, which has empty port
+
+* backlog
+
+  **optional**, **type**: unsigned int
+
+  Set the listen backlog number for tcp sockets. The default value will be used if the specified value is less than 8.
+
+  **default**: 4096
+
+  .. note::
+
+    If the backlog argument is greater than the value in /proc/sys/net/core/somaxconn, then it is silently truncated
+    to that value. Since Linux 5.4, the default in this file is 4096; in earlier kernels, the default value is 128.
+
+* netfilter_mark
+
+  **optional**, **type**: unsigned int
+
+  Set the netfilter mark (SOL_SOCKET, SO_MARK) value for the listening socket. If this field not present,
+  the mark value will not be touch. This value can be used for advanced routing policy or netfilter rules.
+
+* ipv6_only
+
+  **optional**, **type**: bool
+
+  Listen only to ipv6 address only if address is set to [::].
+
+  **default**: false
+
+* instance
+
+  **optional**, **type**: int
+
+  Set how many listen instances. If *scale* is set, this will be the least value.
+
+  **default**: 1
+
+* scale
+
+  **optional**, **type**: float | string
+
+  Set the listen instance count scaled according to available parallelism.
+
+  For string value, it could be in percentage (n%) or fractional (n/d) format.
+
+  Example:
+
+  .. code-block:: yaml
+
+    scale: 1/2
+    # or
+    scale: 0.5
+    # or
+    scale: 50%
+
+  **default**: 0
+
+The yaml value for *listen* can be in the following formats:
+
+* int
+
+  Set the port only.
+
+* :ref:`sockaddr str <conf_value_sockaddr_str>`
+
+  Set ip and port. The port field is required.
+
+* map
+
+  The keys of this map are the fields as described above.
+
+.. _conf_value_tcp_connect:
+
+tcp connect
+===========
+
+**yaml value**: map
+
+This set TCP connect params.
+
+It consists of 2 fields:
+
+* max_retry
+
+  **optional**, **type**: int
+
+  Set the max tcp connect retry for a single upstream connection of the same address family.
+  The total tcp connect tries will be *1 + max_retry*.
+
+  Each resolved IP addr will be tried at most once.
+
+  **default**: 2, which means the total tries is 3
+
+* each_timeout
+
+  **optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  Set the max timeout for each connection to the resolved addr of the upstream.
+
+  **default**: 30s
+
+.. _conf_value_udp_listen:
+
+udp listen
+==========
+
+**yaml value**: mix
+
+It consists of the following fields:
+
+* address
+
+  **required**, **type**: :ref:`env sockaddr str <conf_value_env_sockaddr_str>`
+
+  Set the listen socket address.
+
+  **default**: [::]:0, which has empty port
+
+* ipv6_only
+
+  **optional**, **type**: bool
+
+  Listen only to ipv6 address only if address is set to [::].
+
+  **default**: false
+
+* socket_buffer
+
+  **optional**, **type**: :ref:`socket buffer config <conf_value_socket_buffer_config>`
+
+  Set an explicit socket buffer config.
+
+  **default**: not set
+
+* socket_misc_opts
+
+  **optional**, **type**: :ref:`udp misc sock opts <conf_value_udp_misc_sock_opts>`
+
+  Set misc UDP socket options.
+
+  **default**: not set
+
+* instance
+
+  **optional**, **type**: int
+
+  Set how many listen instances. If *scale* is set, this will be the least value.
+
+  **default**: 1
+
+* scale
+
+  **optional**, **type**: float | string
+
+  Set the listen instance count scaled according to available parallelism.
+
+  For string value, it could be in percentage (n%) or fractional (n/d) format.
+
+  Example:
+
+  .. code-block:: yaml
+
+    scale: 1/2
+    # or
+    scale: 0.5
+    # or
+    scale: 50%
+
+  **default**: 0
+
+The yaml value for *listen* can be in the following formats:
+
+* int
+
+  Set the port only.
+
+* :ref:`sockaddr str <conf_value_sockaddr_str>`
+
+  Set ip and port. The port field is required.
+
+* map
+
+  The keys of this map are the fields as described above.
+
+.. _conf_value_happy_eyeballs:
+
+happy eyeballs
+==============
+
+**yaml value**: map
+
+This set Happy Eyeballs params for multiple tcp connections.
+
+It consists of the following fields:
+
+* resolution_delay
+
+  **optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  The resolution delay time for the wait of the preferred address family after another one is returned.
+
+  **default**: 50ms
+
+* second_resolution_timeout
+
+  **optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  The timeout time for the wait of the second resolution after no running connection attempts.
+
+  **default**: 2s
+
+* first_address_family_count
+
+  **optional**, **type**: usize
+
+  The address to try before use the addresses from another address family.
+
+  **default**: 1
+
+* connection_attempt_delay
+
+  **optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  The delay time before start a new connection after the previous one.
+
+  **default**: 250ms, **min**: 100ms, **max**: 2s
+
+.. _conf_value_tcp_keepalive:
+
+tcp keepalive
+=============
+
+**yaml value**: mix
+
+This set TCP level keepalive settings.
+
+It consists of 2 fields:
+
+* enable
+
+  **optional**, **type**: bool
+
+  Set whether tcp keepalive should be enabled.
+
+  **default**: false, which means you can set limit on other values in case keepalive is needed somewhere
+
+* idle_time
+
+  **optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  Set the keepalive idle time.
+
+  **default**: 60s
+
+* probe_interval
+
+  **optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  Set the probe interval after idle.
+
+  **default**: not set, which means the OS default value will be used
+
+* probe_count
+
+  **optional**, **type**: u32
+
+  Set the probe count.
+
+  **default**: not set, which means the OS default value will be used
+
+If the root value type is bool, the value will be parsed the same as the *enable* key.
+
+If the root value type is not map and not bool, the value will be parsed the same as the *idle_time* key, but with
+*enable* set to true.
+
+.. _conf_value_tcp_misc_sock_opts:
+
+tcp misc sock opts
+==================
+
+**yaml value**: map
+
+This set misc tcp socket options.
+
+Keys:
+
+* no_delay
+
+  **optional**, **type**: bool
+
+  Set value for tcp level socket option TCP_NODELAY. If set to true, disable the Nagle algorithm.
+
+  **default**: the default value varies, check the doc of the outer option
+
+* mss
+
+  **optional**, **type**: u32, **alias**: max_segment_size
+
+  Set value for tcp level socket option TCP_MAXSEG, the maximum segment size for outgoing TCP packets.
+
+  **default**: not set
+
+* ttl
+
+  **optional**, **type**: u32, **alias**: time_to_live
+
+  Set value for ip level socket option IP_TTL, the time-to-live field in each sent packet.
+
+  **default**: not set
+
+* tos
+
+  **optional**, **type**: u8, **alias**: type_of_service
+
+  Set value for ip level socket option IP_TOS, the type-of-service field in each sent packet.
+
+  **default**: not set
+
+* mark
+
+  **optional**, **type**: u32, **alias**: netfilter_mark
+
+  Set value for socket level socket option SO_MARK, the netfilter mark value for our tcp sockets.
+
+  **default**: not set
+
+.. _conf_value_udp_misc_sock_opts:
+
+udp misc sock opts
+==================
+
+**yaml value**: map
+
+This set misc udp socket options.
+
+Keys:
+
+* ttl
+
+  **optional**, **type**: u32, **alias**: time_to_live
+
+  Set value for ip level socket option IP_TTL, the time-to-live field in each sent packet.
+
+  **default**: not set
+
+* tos
+
+  **optional**, **type**: u8, **alias**: type_of_service
+
+  Set value for ip level socket option IP_TOS, the type-of-service field in each sent packet.
+
+  **default**: not set
+
+* mark
+
+  **optional**, **type**: u32, **alias**: netfilter_mark
+
+  Set value for socket level socket option SO_MARK, the netfilter mark value for our tcp sockets.
+
+  **default**: not set
+
+.. _conf_value_http_header_name:
+
+http header name
+================
+
+**yaml value**: str
+
+This string should be a valid HTTP header name.
+
+.. _conf_value_http_keepalive:
+
+http keepalive
+==============
+
+**yaml value**: mix
+
+This set HTTP level keepalive settings.
+
+It consists of 2 fields:
+
+* enable
+
+  **optional**, **type**: bool
+
+  Set whether tcp keepalive should be enabled.
+
+  **default**: true
+
+* idle_expire
+
+  **optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  Set the idle expire time for the saved connection.
+  If the last active time for the connection has elapsed, the connection will be dropped.
+
+  **default**: 60s
+
+If the root value type is bool, the value will be parsed the same as the *enable* key.
+
+If the root value type is not map and not bool, the value will be parsed the same as the *idle_expire* key, but with
+*enable* set to true.
+
+.. _conf_value_http_forwarded_header_type:
+
+http forwarded header type
+==========================
+
+**yaml value**: str | bool
+
+This set the header type we set in requests for identifying the originating IP address of a client connected to us.
+
+The string values are:
+
+* none
+
+  Do not set any header.
+
+* classic
+
+  Use the de-facto standard header *X-Forwarded-For*, this is widely used.
+
+* standard
+
+  Use the standard header *Forwarded* defined in rfc7239. We set both the *for* and the *by* parameter in this case.
+
+If the yaml value type is bool, *true* will be *classic*, and *false* will be none.
+
+.. _conf_value_http_server_id:
+
+http server id
+==============
+
+**yaml value**: str
+
+Set http server id (server name) for http forwarding services.
+
+All characters should be ASCII in range '0x20' - '0x7E', except for ';' and ','.
+
+.. _conf_value_proxy_protocol_version:
+
+proxy protocol version
+======================
+
+**yaml value**: u8
+
+Set the PROXY protocol version.
+
+We support version 1 and version 2 for outgoing tcp connections.

g3tiles/doc/configuration/values/rate_limit.rst

@@ -0,0 +1,176 @@
+
+.. _configure_rate_limit_value_types:
+
+**********
+Rate Limit
+**********
+
+.. _conf_value_tcp_sock_speed_limit:
+
+tcp socket speed limit
+======================
+
+**yaml value**: mix
+
+It consists of 3 fields:
+
+* shift_millis | shift
+
+  **type**: int
+
+  The time slice we use to count is *2 ^ N* milliseconds, where N is set by this key and should be in range [0 - 12].
+  If N is 10, and the time slice is 1024ms. If omitted, this means the limit is not set.
+
+* upload | north | upload_bytes | north_bytes
+
+  **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+  This sets the upload bytes in the time slice. *0* means delay forever.
+
+* download | south | download_bytes | south_bytes
+
+  **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+  This set the max download bytes in the time slice. *0* means delay forever.
+
+The yaml value for *tcp_sock_speed_limit* can be in varies formats:
+
+* :ref:`humanize usize <conf_value_humanize_usize>`
+
+  This will set upload and download to the same value, with shift_millis set to 10.
+
+* map
+
+  The keys of this map are the fields as described above.
+
+.. _conf_value_udp_sock_speed_limit:
+
+udp socket speed limit
+======================
+
+**yaml value**: mix
+
+It consists of 4 fields:
+
+* shift_millis | shift
+
+  **type**: int
+
+  The time slice we use to count is *2 ^ N* milliseconds, where N is set by this key and should be in range [0 - 12].
+  If N is 10, and the time slice is 1024ms. If omitted, this means the limit is not set.
+
+* upload_bytes | north_bytes
+
+  **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+  This sets the upload bytes in the time slice. *0* means no limit.
+
+* download_bytes | south_bytes
+
+  **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+  This set the max download bytes in the time slice. *0* means no limit.
+
+* upload_packets | north_packets
+
+  **type**: int [usize]
+
+  This set the max upload packets in the time slice. *0* means no limit.
+
+* download_packets | south_packets
+
+  **type**: int [usize]
+
+  This set the max download packets in the time slice. *0* means no limit.
+
+The yaml value for *udp_sock_speed_limit* can be in varies formats:
+
+* :ref:`humanize usize <conf_value_humanize_usize>`
+
+  This will set upload and download bytes to the same value, set shift_millis to 10 and disable check on packets.
+
+* map
+
+  The keys of this map are the fields as described above.
+
+.. _conf_value_request_limit:
+
+request limit
+=============
+
+**yaml value**: mix
+
+It consists of 2 fields:
+
+* shift_millis | shift
+
+  **type**: int
+
+  The time slice we use to count is *2 ^ N* milliseconds, where N is set by this key and should be in range [0 - 12].
+  If N is 10, and the time slice is 1024ms. If omitted, this means the limit is not set.
+
+* requests
+
+  **type**: usize
+
+  This sets the max requests in the time slice. 0 is not allowed.
+
+.. _conf_value_rate_limit_quota:
+
+rate limit quota
+================
+
+**yaml value**: mix
+
+It consists of 3 fields:
+
+* rate
+
+  **type**: :ref:`nonzero u32 <conf_value_nonzero_u32>`
+
+  If int or str without any unit, the default unit will be per second.
+
+  Supported units for str:
+
+    - /s, per second
+    - /m, per minute
+    - /h, per hour
+
+* replenish_interval
+
+  **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  Construct a quota that replenishes one cell in a given interval. The default max_burst value is 1 is its not specified
+  along with this option.
+
+* max_burst
+
+  Adjusts the maximum burst size for a quota to construct a rate limiter with a capacity
+  for at most the given number of cells
+
+.. note:: *rate* and *replenish_interval* is conflict with each other, the latter one in conf will take effect.
+
+The yaml value for *u32 limit quota* can be in varies formats:
+
+* simple rate
+
+  Just the rate value. The max_burst value is the same as the one set in the rate.
+
+* map
+
+  The keys of this map are the fields as described above.
+
+.. _conf_value_random_ratio:
+
+random ratio
+============
+
+**yaml value**: f64 | str | bool | integer
+
+Set a random ratio between 0.0 and 1.0 (inclusive).
+
+For *str* value, it can be in fraction form (n/d), in percentage form (n%), or just a float string.
+
+For *bool* value, *false* means 0.0, *true* means 1.0.
+
+For *integer* value, only 0 and 1 is allowed.

g3tiles/doc/configuration/values/route.rst

@@ -0,0 +1,43 @@
+.. _configure_route_value_types:
+
+*****
+Route
+*****
+
+.. _conf_value_host_matched_object:
+
+Host Matched Object
+===================
+
+**yaml value**: map | seq of map
+
+This set a host based match object for generic type T, which will be specified in the real config options.
+
+The yaml value for T will be a map, but with the following keys as reserved as they are used by the match rules:
+
+* exact_match
+
+  **optional**, **type**: :ref:`host <conf_value_host>`
+
+  Match if this is the exact host.
+
+* child_match
+
+  **optional**, **type**: :ref:`domain <conf_value_domain>`
+
+  Match if the target host is a child domain of this parent domain.
+
+* set_default
+
+  **optional**, **type**: bool
+
+  If true, also set this T as default value
+
+  **default**: false
+
+If none of the above keys found, the parsed T value will also be used as the default value.
+
+A match object can contains one or more T(s), which means the yaml type for this object could be a single T,
+or a sequence of T.
+
+Only a single T is allowed for each match rules, including the default one.

g3tiles/doc/configuration/values/runtime.rst

@@ -0,0 +1,75 @@
+
+.. _configure_runtime_value_types:
+
+*******
+Runtime
+*******
+
+.. _conf_value_cpu_set:
+
+cpu set
+=======
+
+**yaml value** seq | usize
+
+A `CPU_SET(3)`_ for use with `sched_setaffinity(2)`_.
+
+The value should be a CPU ID, starting from 0, or a sequence of CPU IDs.
+
+.. _CPU_SET(3): https://man7.org/linux/man-pages/man3/CPU_SET.3.html
+.. _sched_setaffinity(2): https://man7.org/linux/man-pages/man2/sched_setaffinity.2.html
+
+.. _conf_value_unaided_runtime_config:
+
+unaided runtime config
+======================
+
+**yaml value**: map
+
+This is the config for unaided runtime.
+
+The keys are:
+
+thread_number
+-------------
+
+**optional**, **type**: usize
+
+Set the thread number.
+
+**default**: the number of logic CPU cores
+
+thread_stack_size
+-----------------
+
+**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
+
+Set the stack size for worker threads. For *<int>* value, the unit is bytes.
+
+**default**: system default
+
+sched_affinity
+--------------
+
+**optional**, **type**: map | bool
+
+Set the sched affinity for each threads.
+
+For map value, the key should be the thread id starting from 0, and the value should be :ref:`cpu set <conf_value_cpu_set>`.
+
+For bool value:
+
+* if true, a default CPU SET will be set for each thread, the CPU ID in the set will match the thread ID.
+
+* if false, no sched affinity will be set, just as if this config option is not present.
+
+**default**: no sched affinity set
+
+max_io_events_per_tick
+----------------------
+
+**optional**, **type**: usize
+
+Configures the max number of events to be processed per tick.
+
+**default**: 1024, tokio default value

g3tiles/doc/configuration/values/tls.rst

@@ -0,0 +1,434 @@
+
+.. _configure_tls_value_types:
+
+***
+TLS
+***
+
+.. _conf_value_tls_name:
+
+tls name
+========
+
+**yaml type**: :ref:`host <conf_value_host>`
+
+Set the dns name / ip address for server certificate verification.
+If not set, the corresponding upstream address will be used.
+
+.. _conf_value_tls_certificates:
+
+tls certificates
+================
+
+**yaml type**: :ref:`file <conf_value_file>` | seq
+
+Set the certificate file(s), which should be in PEM format(`openssl-req(1)`_).
+
+If relative, it will be searched in the directory that contains current config file.
+
+.. _openssl-req(1): https://www.openssl.org/docs/manmaster/man1/openssl-req.html
+
+.. _conf_value_tls_private_key:
+
+tls private_key
+===============
+
+**yaml type**: :ref:`file <conf_value_file>`
+
+Set the private key file, which should be in PKCS#8(`openssl-genpkey(1)`_) or traditional PEM format.
+
+If relative, it will be searched in the directory that contains current config file.
+The last one in the file will be used if many keys are found.
+
+.. _openssl-genpkey(1): https://www.openssl.org/docs/manmaster/man1/openssl-genpkey.html
+
+.. _conf_value_tls_cert_pair:
+
+tls cert pair
+=============
+
+**yaml value**: map
+
+A pair value contains tls certificate and private key.
+
+The keys are:
+
+* certificate
+
+  **required**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
+
+  Set client certificates if client auth is needed by remote server.
+  Private key must also be set if client auth is needed.
+
+  **default**: not set
+
+* private_key
+
+  **required**, **type**: :ref:`tls private_key <conf_value_tls_private_key>`
+
+  Set the private key for client if client auth is needed by remote server.
+  Client certificates are also needed if client auth is needed.
+
+  **default**: not set
+
+.. _conf_value_tlcp_cert_pair:
+
+tlcp cert pair
+==============
+
+**yaml value**: map
+
+A pair value contains tlcp certificate and private key.
+
+The keys are:
+
+* sign_certificate
+
+  **required**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
+
+  Set client sign certificates if client auth is needed by remote server.
+  Private key must also be set if client auth is needed.
+
+  **default**: not set
+
+* sign_private_key
+
+  **required**, **type**: :ref:`tls private_key <conf_value_tls_private_key>`
+
+  Set the sign private key for client if client auth is needed by remote server.
+  Client certificates are also needed if client auth is needed.
+
+  **default**: not set
+
+* enc_certificate
+
+  **required**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
+
+  Set client enc certificates if client auth is needed by remote server.
+  Private key must also be set if client auth is needed.
+
+  **default**: not set
+
+* enc_private_key
+
+  **required**, **type**: :ref:`tls private_key <conf_value_tls_private_key>`
+
+  Set the enc private key for client if client auth is needed by remote server.
+  Client certificates are also needed if client auth is needed.
+
+  **default**: not set
+
+.. _conf_value_openssl_protocol:
+
+openssl protocol
+================
+
+**yaml value**: string
+
+Set openssl protocol version.
+
+Current supported values are:
+
+- tls1.2
+- tls1.3
+- tlcp (only if vendored-tongsuo feature is enabled)
+
+.. _conf_value_openssl_ciphers:
+
+openssl ciphers
+===============
+
+**yaml value**: string or seq
+
+Set openssl cipher list or ciphersuites for the specified protocol.
+
+Values can be obtained from `openssl ciphers -v` command.
+
+For string value, it can be ciphers joined by ':'.
+
+For seq value, each one should be a cipher string.
+
+.. _conf_value_openssl_tls_client_config:
+
+openssl tls client config
+=========================
+
+**yaml value**: map
+
+The tls config to be used as a tls client.
+
+The map is consists of the following fields:
+
+* protocol
+
+  **optional**, **type**: :ref:`openssl protocol <conf_value_openssl_protocol>`
+
+  Set to use a specific protocol version.
+
+  **default**: not set
+
+* ciphers
+
+  **optional**, **type**: :ref:`openssl ciphers <conf_value_openssl_ciphers>`
+  **require**: protocol
+
+  Set to use a specific set of ciphers for the specified protocol version.
+
+  **default**: not set
+
+* disable_sni
+
+  **optional**, **type**: bool
+
+  Whether to send the Server Name Indication (SNI) extension during the client handshake.
+
+  **default**: false
+
+* cert_pair
+
+  **optional**, **type**: :ref:`tls cert pair <conf_value_tls_cert_pair>`
+  **conflict**: certificate, private_key
+
+  Set the client certificate and private key pair.
+
+  **default**: not set
+
+* tlcp_cert_pair
+
+  **optional**, **type**: :ref:`tlcp cert pair <conf_value_tlcp_cert_pair>`
+
+  Set the client certificate and private key pair for TLCP protocol.
+  This will be in effect only if protocol is set to tlcp.
+
+  **default**: not set
+
+* ca_certificate | server_auth_certificate
+
+  **optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
+
+  A list of certificates for server auth. If not set, the system default ca certificates will be used.
+
+  **default**: not set
+
+* no_default_ca_certificate
+
+  **optional**, **type**: bool
+
+  Set if you don't want to load default ca certificates.
+
+  **default**: false
+
+* handshake_timeout
+
+  **optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  Set the tls handshake timeout value.
+
+  **default**: 10s
+
+* no_session_cache
+
+  **optional**, **type**: bool
+
+  Set if you want to disable cache of TLS sessions.
+
+  **default**: false
+
+* use_builtin_session_cache
+
+  **optional**, **type**: bool
+
+  Set if we should use OpenSSL builtin session cache.
+
+  **default**: false
+
+* session_cache_lru_max_sites
+
+  **optional**, **type**: usize
+
+  Set how many LRU sites should have cached sessions.
+
+  Only in use if this tls client is used by many sites.
+
+  **default**: 128
+
+* session_cache_each_capacity
+
+  **optional**, **type**: usize
+
+  Set how many sessions should be kept for each site.
+
+  **default**: 16
+
+* supported_groups
+
+  **optional**, **type**: str
+
+  Set the supported elliptic curve groups.
+
+  **default**: not set
+
+* use_ocsp_stapling
+
+  **optional**, **type**: bool
+
+  Set this to true to request a stapled OCSP response from the server.
+
+  Verify of this response is still not implemented.
+
+  **default**: not set, the default value may vary between different OpenSSL variants
+
+* enable_sct
+
+  **optional**, **type**: bool
+
+  Enable the processing of signed certificate timestamps (SCTs) for OpenSSL, or enables SCT requests for BoringSSL.
+
+  Verify of this response is still not implemented for BoringSSL variants.
+
+  **default**: not set, the default value may vary between different OpenSSL variants
+
+* enable_grease
+
+  **optional**, **type**: bool
+
+  Enable GREASE. See `RFC 8701`_.
+
+  **default**: not set, the default value may vary between different OpenSSL variants
+
+  .. _RFC 8701: https://datatracker.ietf.org/doc/rfc8701/
+
+* permute_extensions
+
+  **optional**, **type**: bool
+
+  Whether to permute TLS extensions.
+
+  **default**: not set, the default value may vary between different OpenSSL variants
+
+.. _conf_value_rustls_client_config:
+
+rustls client config
+====================
+
+**yaml value**: map
+
+The tls config to be used as a tls client.
+
+The map is consists of the following fields:
+
+* no_session_cache
+
+  **optional**, **type**: bool
+
+  Set if you want to disable cache of TLS sessions.
+
+  **default**: false
+
+* disable_sni
+
+  **optional**, **type**: bool
+
+  Whether to send the Server Name Indication (SNI) extension during the client handshake.
+
+  **default**: false
+
+* max_fragment_size
+
+  **optional**, **type**: usize
+
+  Set the maximum size of TLS message we'll emit.
+
+  **default**: default value in tls driver
+
+* cert_pair
+
+  **optional**, **type**: :ref:`tls cert pair <conf_value_tls_cert_pair>`
+  **conflict**: certificate, private_key
+
+  Set the client certificate and private key pair.
+
+  **default**: not set
+
+* ca_certificate | server_auth_certificate
+
+  **optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
+
+  A list of certificates for server auth. If not set, the system default ca certificates will be used.
+
+  **default**: not set
+
+* no_default_ca_certificate
+
+  **optional**, **type**: bool
+
+  Set if you don't want to load default ca certificates.
+
+  **default**: false
+
+* use_builtin_ca_certificate
+
+  **optional**, **type**: bool
+
+  Set to true if you want to use built in webpki-roots ca certificates as default ca certificates.
+
+  **default**: false
+
+* handshake_timeout
+
+  **optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  Set the tls handshake timeout value.
+
+  **default**: 10s
+
+.. _conf_value_rustls_server_config:
+
+rustls server config
+====================
+
+**yaml value**: map
+
+The tls config to be used as a tls server.
+
+The map is consists of the following fields:
+
+* cert_pairs
+
+  **optional**, **type**: :ref:`tls cert pair <conf_value_tls_cert_pair>` or seq
+
+  Set certificate and private key pairs for this TLS server.
+
+  .. note:: At least set this or certificate & private_key.
+
+* enable_client_auth
+
+  **optional**, **type**: bool
+
+  Set if you want to enable client auth.
+
+  **default**: disabled
+
+* use_session_ticket
+
+  **optional**, **type**: bool
+
+  Set if we should enable TLS session ticket to do TLS Session Resumption without Server-Side State.
+
+  **default**: disabled
+
+* ca_certificate | client_auth_certificate
+
+  **optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
+
+  A list of certificates for client auth. If not set, the system default ca certificates will be used.
+
+  **default**: not set
+
+* handshake_timeout
+
+  **optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
+
+  Set the tls handshake timeout value.
+
+  **default**: 10s

g3tiles/doc/index.rst

@@ -0,0 +1,22 @@
+.. g3tiles documentation master file, created by
+   sphinx-quickstart on Mon Apr  8 11:00:51 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to g3tiles's documentation!
+===================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   configuration/index
+   metrics/index
+   log/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

g3tiles/doc/log/index.rst

@@ -0,0 +1,60 @@
+.. _log:
+
+###
+Log
+###
+
+We support many logging drivers, see :ref:`log <configuration_log>` for more details.
+
+All generated logs is structured, we will describe the structures of all type of logs we generated in this doc.
+
+Shared Keys
+===========
+
+The following shared keys are set in all type of logs:
+
+daemon_name
+-----------
+
+**optional**, **type**: string
+
+The daemon group name of the process, which can be set by using of command line options.
+
+pid
+---
+
+**required**, **type**: int
+
+The pid of the process.
+
+There may be many processes running, one online and the others in offline mode.
+
+log_type
+--------
+
+**required**, **type**: enum string
+
+Show the log type. The meaning of non-shared keys are depend on this value.
+
+Values are:
+
+  * Task
+
+.. _log_shared_keys_report_ts:
+
+report_ts
+---------
+
+**optional**, **type**: unix timestamp
+
+Show the timestamp when we generate this log.
+
+It will be present if the log driver has been configured to append it, see :ref:`log driver <configuration_log_driver>`
+for more info.
+
+Log Types
+=========
+
+.. toctree::
+
+   task/index

g3tiles/doc/log/task/index.rst

@@ -0,0 +1,137 @@
+.. _log_task:
+
+********
+Task Log
+********
+
+Each valid request will be a task. Each task will generate one log when finished.
+
+Shared Keys
+===========
+
+The following shared keys are set in all type of task logs:
+
+server_type
+-----------
+
+**required**, **type**: enum string
+
+The type of the server that accepted the request.
+
+server_name
+-----------
+
+**required**, **type**: string
+
+The name of the server that accepted the request.
+
+task_type
+---------
+
+**required**, **type**: enum string
+
+The subtype of this task log. The meaning of non-shared keys are depend on this value.
+
+task_id
+-------
+
+**required**, **type**: uuid in simple string format
+
+UUID of the task.
+
+The *task_id* will appear in other logs such as escape log if they have any association with this task.
+
+stage
+-----
+
+**required**, **type**: enum string
+
+The stage of the task.
+
+The values available for each task depend on the server protocol. Here is all values:
+
+* Created
+
+  The task has just been created.
+
+* Preparing
+
+  We are preparing internal resources.
+
+* Connecting
+
+  We are trying to connect to remote peer.
+
+* Connected
+
+  We have just connected to remote peer.
+
+* Replying
+
+  We are trying to reply to clients that we have connected to remote peer.
+
+* LoggedIn
+
+  The upstream needs login and we have logged in.
+
+* Relaying
+
+  Both client and remote channel established, we are relaying data now.
+
+* Finished
+
+  The task has finished with no error. Only available for layer 7 protocols.
+
+start_at
+--------
+
+**required**, **type**: rfc3339 timestamp string with microseconds
+
+The time that the task is created (after validation).
+
+.. note:: Not every request will be a task, only the valid ones.
+
+reason
+------
+
+**required**, **type**: enum string
+
+The brief reason why the task ends.
+
+See the definition of **ServerTaskError** in code file *src/serve/error.rs*.
+
+wait_time
+---------
+
+**optional**, **type**: time duration string
+
+Show how many time spent from the acceptation of the request to the creation of the task.
+
+For requests that reuse old connection, the start time will be the time we start to polling the next request,
+so you may see very large wait_time in logs. This behaviour may change in future.
+
+.. _log_task_ready_time:
+
+ready_time
+----------
+
+**optional**, **type**: time duration string
+
+Show how many time spent from the creation of the task to the relaying stage, which means both the client channel
+and the remote channel have been established. The value may be empty if the task failed early.
+
+total_time
+----------
+
+**required**, **type**: time duration string
+
+Show the time from the creation of the task to the end of the task.
+
+Sub Types
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   tcp_connect
+   keyless

g3tiles/doc/log/task/keyless.rst

@@ -0,0 +1,63 @@
+.. _log_task_keyless:
+
+*******
+Keyless
+*******
+
+The following keys are available for Keyless task log:
+
+server_addr
+-----------
+
+**required**, **type**: socket address string
+
+The listening address of the server.
+
+client_addr
+-----------
+
+**required**, **type**: socket address string
+
+The client address.
+
+req_total
+---------
+
+**required**, **type**: usize
+
+Total requests.
+
+req_pass
+--------
+
+**required**, **type**: usize
+
+Passed requests.
+
+req_fail
+--------
+
+**required**, **type**: usize
+
+Failed requests.
+
+rsp_drop
+--------
+
+**required**, **type**: usize
+
+Dropped responses.
+
+rsp_pass
+--------
+
+**required**, **type**: usize
+
+Passed responses.
+
+rsp_fail
+--------
+
+**required**, **type**: usize
+
+Failed responses.

g3tiles/doc/log/task/tcp_connect.rst

@@ -0,0 +1,49 @@
+.. _log_task_tcp_connect:
+
+***********
+Tcp Connect
+***********
+
+The following keys are available for TcpConnect task log:
+
+server_addr
+-----------
+
+**required**, **type**: socket address string
+
+The listening address of the server.
+
+client_addr
+-----------
+
+**required**, **type**: socket address string
+
+The client address.
+
+c_rd_bytes
+----------
+
+**optional**, **type**: int
+
+How many bytes we have received from client.
+
+c_wr_bytes
+----------
+
+**optional**, **type**: int
+
+How many bytes we have sent to client.
+
+r_rd_bytes
+----------
+
+**optional**, **type**: int
+
+How many bytes we have received from the remote peer.
+
+r_wr_bytes
+----------
+
+**optional**, **type**: int
+
+How many bytes we have sent to the remote peer.

g3tiles/doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

g3tiles/doc/metrics/backend/index.rst

@@ -0,0 +1,21 @@
+.. _metrics_backend:
+
+###############
+Backend Metrics
+###############
+
+The backend metrics are grouped by task type.
+
+The following are the tags for all backend metrics:
+
+* :ref:`daemon_group <metrics_tag_daemon_group>`
+* :ref:`stat_id <metrics_tag_stat_id>`
+
+* backend
+
+  Show the backend name.
+
+.. toctree::
+
+   stream
+   keyless

g3tiles/doc/metrics/backend/keyless.rst

@@ -0,0 +1,84 @@
+.. _metrics_backend_keyless:
+
+#######################
+Keyless Backend Metrics
+#######################
+
+Connection Metrics
+==================
+
+No extra tags.
+
+The metric names are:
+
+* backend.keyless.connection.attempt
+
+  **type**: count
+
+  Show the connect attempt count.
+
+* backend.keyless.connection.established
+
+  **type**: count
+
+  Show the count of successful connection.
+
+Request Metrics
+===============
+
+* backend.keyless.request.recv
+
+  **type**: count
+
+  Show the count of requests received.
+
+* backend.keyless.request.send
+
+  **type**: count
+
+  Show the count of requests sent to the target peer.
+
+* backend.keyless.request.drop
+
+  **type**: count
+
+  Show the count of requests that get dropped internally.
+
+* backend.keyless.response.recv
+
+  **type**: count
+
+  Show the count of responses received from the target peer.
+
+* backend.keyless.response.send
+
+  **type**: count
+
+  Show the count of responses sent to the client.
+
+* backend.keyless.response.drop
+
+  **type**: count
+
+  Show the count of responses that get dropped internally.
+
+Duration Metrics
+================
+
+The following tag is also set:
+
+* :ref:`quantile <metrics_tag_quantile>`
+
+The metric names are:
+
+* backend.keyless.wait.duration
+
+  **type**: gauge
+
+  Show the internal queue wait duration stats.
+
+* backend.keyless.response.duration
+
+  **type**: gauge
+
+  Show the upstream response duration stats.

g3tiles/doc/metrics/backend/stream.rst

@@ -0,0 +1,39 @@
+.. _metrics_backend_stream:
+
+######################
+Stream Backend Metrics
+######################
+
+Connection Metrics
+==================
+
+No extra tags.
+
+The metric names are:
+
+* backend.stream.connection.attempt
+
+  **type**: count
+
+  Show the connect attempt count.
+
+* backend.stream.connection.established
+
+  **type**: count
+
+  Show the count successful connection.
+
+Duration Metrics
+================
+
+The following tag is also set:
+
+* :ref:`quantile <metrics_tag_quantile>`
+
+The metric names are:
+
+* backend.stream.connect.duration
+
+  **type**: gauge
+
+  Show the tcp connect ready time duration.

g3tiles/doc/metrics/index.rst

@@ -0,0 +1,58 @@
+.. _metrics:
+
+#######
+Metrics
+#######
+
+Currently we only support send metrics to statsd, see :ref:`stat <configuration_stat>` for more details.
+
+The following is the common tags for all metrics:
+
+.. _metrics_tag_daemon_group:
+
+* daemon_group
+
+  This tag is the same as the daemon group specified in config file or command args.
+
+.. _metrics_tag_stat_id:
+
+* stat_id
+
+  A machine local unique stat_id for dedup purpose. It should be **dropped** by statsd, and the metrics with the same
+  remaining tags should be aggregated.
+
+.. _metrics_tag_transport:
+
+* transport
+
+  Show the transport layer protocol. Values are:
+
+  - tcp
+  - udp
+
+.. _metrics_tag_quantile:
+
+* quantile
+
+  Show the quantile value for histogram stats.
+
+  The following values are always persent:
+
+  - min
+  - max
+  - mean
+
+  Values can be added by :ref:`histogram metrics <conf_value_histogram_metrics>` config.
+  If not set, the following values are added by default:
+
+  - 0.50
+  - 0.80
+  - 0.90
+  - 0.95
+  - 0.99
+
+.. toctree::
+
+   server
+   logger
+   backend/index

g3tiles/doc/metrics/logger.rst

@@ -0,0 +1,52 @@
+.. _metrics_logger:
+
+##############
+Logger Metrics
+##############
+
+The metrics for loggers that support metrics.
+
+The *discard* and *journal* log driver do not support metrics, see config for :ref:`log <configuration_log>`.
+
+The following are the tags for all logger metrics:
+
+* :ref:`daemon_group <metrics_tag_daemon_group>`
+* :ref:`stat_id <metrics_tag_stat_id>`
+
+* logger
+
+  Show the name of the logger.
+
+The metrics are:
+
+* logger.message.total
+
+  **type**: count
+
+  Show the total number of logs.
+
+* logger.message.pass
+
+  **type**: count
+
+  Show the number of logs passed to next peer.
+
+* logger.traffic.pass
+
+  **type**: count
+
+  Show the bytes of log that has been sent to next peer.
+
+* logger.message.drop
+
+  Show the number of logs that has been dropped.
+
+  An extra tag **drop_type** is used to add more details for the drop reason, values are:
+
+  - FormatFailed: the message can not be formatted to match the real log protocol
+
+  - ChannelClosed: the internal async channel has been closed.
+
+  - ChannelOverflow: the internal async channel is full.
+
+  - PeerUnreachable: the next peer is closed or currently unreachable.

g3tiles/doc/metrics/server.rst

@@ -0,0 +1,123 @@
+.. _metrics_server:
+
+##############
+Server Metrics
+##############
+
+The metrics in server side shows the stats with client, and can be grouped to *request* and *traffic* types.
+
+The following are the tags for all server metrics:
+
+* :ref:`daemon_group <metrics_tag_daemon_group>`
+* :ref:`stat_id <metrics_tag_stat_id>`
+
+* server
+
+  Show the server name.
+
+* online
+
+  Show if the server is online. The value is either 'y' or 'n'.
+
+Listen
+======
+
+No extra tags.
+
+The metric names are:
+
+* listen.instance.count
+
+  **type**: gauge
+
+  Show how many listening sockets.
+
+* listen.accepted
+
+  **type**: count
+
+  Show how many client connections has been accepted.
+
+* listen.dropped
+
+  **type**: count
+
+  Show how many client connections has been dropped by acl rules at early stage.
+
+* listen.timeout
+
+  **type**: count
+
+  Show how many client connections has been timed out in early protocol negotiation (such as TLS).
+
+* listen.failed
+
+  **type**: count
+
+  Show how many times of accept error.
+
+Request
+=======
+
+No other fixed tags. Extra tags set at server side will be added.
+
+The metric names are:
+
+* server.connection.total
+
+  **type**: count
+
+  Show how many client connections has been accepted.
+
+* server.task.total
+
+  **type**: count
+
+  Show how many valid tasks has been spawned. Each client connection will be promoted to task only if the negotiation
+  success. User authentication is also taken into count in negotiation stage.
+
+* server.task.alive
+
+  **type**: gauge
+
+  Show how many alive tasks that spawned by this server are running. In normal case the daemon stopped by systemd,
+  servers with running tasks will goto offline mode, and wait all tasks to be stopped.
+
+Traffic
+=======
+
+The following tags are also set:
+
+* :ref:`transport <metrics_tag_transport>`
+
+Extra tags set at server side will be added.
+
+The io stats here only include application layer stats, the other layer such TLS stats are not included.
+
+The metric names are:
+
+* server.traffic.in.bytes
+
+  **type**: count
+
+  Show the total bytes of incoming bytes from client.
+
+* server.traffic.in.packets
+
+  **type**: count
+
+  Show the total datagram packets received from client.
+  Note that this is not available for stream type transport protocols.
+
+* server.traffic.out.bytes
+
+  **type**: count
+
+  Show the total bytes that the server has sent to the client.
+
+* server.traffic.out.packets
+
+  **type**: count
+
+  Show the total datagram packets that the server has sent to the client.
+  Note that this is not available for stream type transport protocols.

g3tiles/examples/benchmark/server.d/openssl.yaml

@@ -6,7 +6,7 @@ listen:
   address: "[::]:9093"
 listen_in_worker: true
 
-hosts:
+virtual_hosts:
   name: bench
   exact_match: bench.example.net
   cert_pairs:

g3tiles/examples/benchmark/server.d/rustls.yaml

@@ -6,7 +6,7 @@ listen:
   address: "[::]:9095"
 listen_in_worker: true
 
-hosts:
+virtual_hosts:
   name: bench
   exact_match: bench.example.net
   cert_pairs:

g3tiles/src/config/server/keyless_proxy.rs

@@ -21,10 +21,8 @@ use anyhow::{anyhow, Context};
 use ascii::AsciiString;
 use yaml_rust::{yaml, Yaml};
 
-use g3_io_ext::LimitedCopyConfig;
 use g3_types::acl::AclNetworkRuleBuilder;
 use g3_types::metrics::{MetricsName, StaticMetricsTags};
-use g3_types::net::{TcpMiscSockOpts, TcpSockSpeedLimitConfig};
 use g3_yaml::YamlDocPosition;
 
 use super::{ServerConfig, IDLE_CHECK_DEFAULT_DURATION, IDLE_CHECK_MAXIMUM_DURATION};
@@ -39,11 +37,8 @@ pub(crate) struct KeylessProxyServerConfig {
     pub(crate) shared_logger: Option<AsciiString>,
     pub(crate) ingress_net_filter: Option<AclNetworkRuleBuilder>,
     pub(crate) extra_metrics_tags: Option<Arc<StaticMetricsTags>>,
-    pub(crate) tcp_sock_speed_limit: TcpSockSpeedLimitConfig,
     pub(crate) task_idle_check_duration: Duration,
     pub(crate) task_idle_max_count: i32,
-    pub(crate) tcp_copy: LimitedCopyConfig,
-    pub(crate) tcp_misc_opts: TcpMiscSockOpts,
     pub(crate) spawn_task_unconstrained: bool,
     pub(crate) backend: MetricsName,
 }
@@ -56,11 +51,8 @@ impl KeylessProxyServerConfig {
             shared_logger: None,
             ingress_net_filter: None,
             extra_metrics_tags: None,
-            tcp_sock_speed_limit: TcpSockSpeedLimitConfig::default(),
             task_idle_check_duration: IDLE_CHECK_DEFAULT_DURATION,
             task_idle_max_count: 1,
-            tcp_copy: Default::default(),
-            tcp_misc_opts: Default::default(),
             spawn_task_unconstrained: false,
             backend: MetricsName::default(),
         }
@@ -116,11 +108,6 @@ impl KeylessProxyServerConfig {
                 self.ingress_net_filter = Some(filter);
                 Ok(())
             }
-            "tcp_sock_speed_limit" | "tcp_conn_speed_limit" => {
-                self.tcp_sock_speed_limit = g3_yaml::value::as_tcp_sock_speed_limit(v)
-                    .context(format!("invalid tcp socket speed limit value for key {k}"))?;
-                Ok(())
-            }
             "task_idle_check_duration" => {
                 self.task_idle_check_duration = g3_yaml::humanize::as_duration(v)
                     .context(format!("invalid humanize duration value for key {k}"))?;
@@ -131,23 +118,6 @@ impl KeylessProxyServerConfig {
                     g3_yaml::value::as_i32(v).context(format!("invalid i32 value for key {k}"))?;
                 Ok(())
             }
-            "tcp_copy_buffer_size" => {
-                let buffer_size = g3_yaml::humanize::as_usize(v)
-                    .context(format!("invalid humanize usize value for key {k}"))?;
-                self.tcp_copy.set_buffer_size(buffer_size);
-                Ok(())
-            }
-            "tcp_copy_yield_size" => {
-                let yield_size = g3_yaml::humanize::as_usize(v)
-                    .context(format!("invalid humanize usize value for key {k}"))?;
-                self.tcp_copy.set_yield_size(yield_size);
-                Ok(())
-            }
-            "tcp_misc_opts" => {
-                self.tcp_misc_opts = g3_yaml::value::as_tcp_misc_sock_opts(v)
-                    .context(format!("invalid tcp misc sock opts value for key {k}"))?;
-                Ok(())
-            }
             "spawn_task_unconstrained" | "task_unconstrained" => {
                 self.spawn_task_unconstrained = g3_yaml::value::as_bool(v)?;
                 Ok(())

g3tiles/src/config/server/openssl_proxy/mod.rs

@@ -150,7 +150,7 @@ impl OpensslProxyServerConfig {
                     .context(format!("invalid humanize duration value for key {k}"))?;
                 Ok(())
             }
-            "hosts" => {
+            "virtual_hosts" | "hosts" => {
                 self.hosts = g3_yaml::value::as_host_matched_obj(v, self.position.as_ref())?;
                 Ok(())
             }

g3tiles/src/config/server/rustls_proxy/mod.rs

@@ -141,7 +141,7 @@ impl RustlsProxyServerConfig {
                 self.client_hello_recv_timeout = timeout;
                 Ok(())
             }
-            "hosts" => {
+            "virtual_hosts" | "hosts" => {
                 self.hosts = g3_yaml::value::as_host_matched_obj(v, self.position.as_ref())?;
                 Ok(())
             }