{"_id":"@bufbuild/knitgateway","_rev":"26-7f664471710bfc0593ddc83c7527a746","name":"@bufbuild/knitgateway","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.2":{"name":"@bufbuild/knitgateway","version":"0.0.2","license":"Apache-2.0","_id":"@bufbuild/knitgateway@0.0.2","maintainers":[{"name":"mdolgos","email":"mdolgos@buf.build"},{"name":"srikrsna-buf","email":"skrishna@buf.build"},{"name":"cmahony","email":"cmahony@buf.build"},{"name":"gwong-buf","email":"gwong@buf.build"},{"name":"dfyock-buf","email":"dfyock@buf.build"},{"name":"dimitropoulos-bufbuild","email":"dmitropoulos@buf.build"},{"name":"jdailey_buf","email":"jdailey@buf.build"},{"name":"sayers-buf","email":"sayers@buf.build"},{"name":"psachs-buf","email":"psachs@buf.build"},{"name":"bufbot","email":"bot@buf.build"},{"name":"tstamm-buf","email":"tstamm@buf.build"},{"name":"bufdev","email":"pedge@buf.build"}],"homepage":"https://github.com/bufbuild/knit-go#readme","bugs":{"url":"https://github.com/bufbuild/knit-go/issues"},"bin":{"knitgateway":"bin/knitgateway"},"dist":{"shasum":"d2885c08cc74583d7fd6722149c63364467fd940","tarball":"https://registry.npmjs.org/@bufbuild/knitgateway/-/knitgateway-0.0.2.tgz","fileCount":5,"integrity":"sha512-FnFdRXxkeAdbb1VF6WGPc/Q7vnRZX6AX+BYxsEzz+CvlIo7rlCJ+pkqa5M79nNRx7CJIYxtKkqnnL1KvY4FuMg==","signatures":[{"sig":"MEQCIBQRHd+qh1dU6wHi91AuwwQYysrjVM2hBmWPNoWJAjbtAiA2XKleszchOuZLIfbXC0itD66TRMQiLpmfW6rsSV1g2w==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":36101},"main":"index.js","engines":{"node":">=12"},"gitHead":"98acd4cf064f6fef581bca5a5a6551abc6ba45da","scripts":{"prepack":"node ./prepack.js","postinstall":"node ./install.js"},"_npmUser":{"name":"srikrsna-buf","email":"skrishna@buf.build"},"repository":{"url":"git+https://github.com/bufbuild/knit-go.git","type":"git"},"_npmVersion":"9.4.0","description":"The Knit standalone gateway.","directories":{},"_nodeVersion":"19.6.0","dependencies":{"@bufbuild/knitgateway-linux-x64":"0.0.2","@bufbuild/knitgateway-win32-x64":"0.0.2","@bufbuild/knitgateway-darwin-x64":"0.0.2","@bufbuild/knitgateway-win32-arm64":"0.0.2","@bufbuild/knitgateway-darwin-arm64":"0.0.2","@bufbuild/knitgateway-linux-aarch64":"0.0.2"},"_hasShrinkwrap":false,"devDependencies":{"esbuild":"^0.17.5","typescript":"4.9.5","@types/node":"18.11.18"},"optionalDependencies":{"@bufbuild/knitgateway-linux-x64":"0.0.2","@bufbuild/knitgateway-win32-x64":"0.0.2","@bufbuild/knitgateway-darwin-x64":"0.0.2","@bufbuild/knitgateway-win32-arm64":"0.0.2","@bufbuild/knitgateway-darwin-arm64":"0.0.2","@bufbuild/knitgateway-linux-aarch64":"0.0.2"},"_npmOperationalInternal":{"tmp":"tmp/knitgateway_0.0.2_1685098262734_0.9002115630149774","host":"s3://npm-registry-packages"}},"0.1.0":{"name":"@bufbuild/knitgateway","version":"0.1.0","license":"Apache-2.0","_id":"@bufbuild/knitgateway@0.1.0","maintainers":[{"name":"srikrsna-buf","email":"skrishna@buf.build"},{"name":"cmahony","email":"cmahony@buf.build"},{"name":"gwong-buf","email":"gwong@buf.build"},{"name":"dfyock-buf","email":"dfyock@buf.build"},{"name":"jdailey_buf","email":"jdailey@buf.build"},{"name":"sayers-buf","email":"sayers@buf.build"},{"name":"psachs-buf","email":"psachs@buf.build"},{"name":"bufbot","email":"bot@buf.build"},{"name":"tstamm-buf","email":"tstamm@buf.build"},{"name":"bufdev","email":"pedge@buf.build"}],"homepage":"https://github.com/bufbuild/knit-go#readme","bugs":{"url":"https://github.com/bufbuild/knit-go/issues"},"bin":{"knitgateway":"bin/knitgateway"},"dist":{"shasum":"dd004d91a455ab2a23bd1cf196da8dfc17aac1c6","tarball":"https://registry.npmjs.org/@bufbuild/knitgateway/-/knitgateway-0.1.0.tgz","fileCount":5,"integrity":"sha512-Q6P8w94dzoj3URwqfrhjGRrsrv2OnrVNzW002hDtc8PZADzh89Q/LToau0bm2GqJZQFDfUXd42qnfIK15ziNFQ==","signatures":[{"sig":"MEUCIQCtuxkZ6rbxLGKkgx5LUQ/4iFBUhErPTyHaz4EpBUnY9QIgSfsq1AYfb390bFw6NBwKabRXlhSmGQofzDyaMDiJHUQ=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":36672},"main":"index.js","engines":{"node":">=12"},"gitHead":"2592a2d3bf43315f560b140e441c036c0459b628","scripts":{"prepack":"node ./prepack.js","postinstall":"node ./install.js"},"_npmUser":{"name":"srikrsna-buf","email":"skrishna@buf.build"},"repository":{"url":"git+https://github.com/bufbuild/knit-go.git","type":"git"},"_npmVersion":"10.1.0","description":"The Knit standalone gateway.","directories":{},"_nodeVersion":"20.7.0","_hasShrinkwrap":false,"devDependencies":{"esbuild":"^0.17.5","typescript":"4.9.5","@types/node":"18.11.18"},"optionalDependencies":{"@bufbuild/knitgateway-linux-x64":"0.1.0","@bufbuild/knitgateway-win32-x64":"0.1.0","@bufbuild/knitgateway-darwin-x64":"0.1.0","@bufbuild/knitgateway-win32-arm64":"0.1.0","@bufbuild/knitgateway-darwin-arm64":"0.1.0","@bufbuild/knitgateway-linux-aarch64":"0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/knitgateway_0.1.0_1696530763307_0.5546245777249963","host":"s3://npm-registry-packages"}}},"time":{"created":"2023-05-26T10:04:52.384Z","modified":"2026-09-16T06:38:31.285Z","0.0.2-test-2":"2023-05-26T10:04:52.834Z","0.0.2-test-3":"2023-05-26T10:11:16.641Z","0.0.2-test-4":"2023-05-26T10:33:47.972Z","0.0.2-test-5":"2023-05-26T10:36:37.402Z","0.0.2":"2023-05-26T10:51:02.902Z","0.1.0":"2023-10-05T18:32:43.486Z"},"bugs":{"url":"https://github.com/bufbuild/knit-go/issues"},"license":"Apache-2.0","homepage":"https://github.com/bufbuild/knit-go#readme","repository":{"url":"git+https://github.com/bufbuild/knit-go.git","type":"git"},"description":"The Knit standalone gateway.","maintainers":[{"email":"pedge@buf.build","name":"bufdev"},{"email":"tstamm@buf.build","name":"tstamm-buf"},{"email":"bot@buf.build","name":"bufbot"},{"email":"jdailey@buf.build","name":"jdailey_buf"},{"email":"dkeung@buf.build","name":"doriakeung"},{"email":"cmahony@buf.build","name":"cmahony"},{"email":"kmcdonald@buf.build","name":"kmcdonald-buf"}],"readme":"# Knit Gateway\n\nThe Knit Gateway. Knit brings GraphQL like capabilities to RPCs. It is built on top of\n[Protobuf](https://protobuf.com/) and [Connect](https://connect.build). This package\ncontains the Knit Gateway binary.\n\nLearn more about Knit at [github.com/bufbuild/knit](https://github.com/bufbuild/knit).\n# Configuration for `knitgateway`\n\nThis document describes the configuration options for the `knitgateway`\nprogram.\n\nThere is a an example config file in the root of this repo named\n[`knitgateway.example.yaml`](/knitgateway.example.yaml).\nThe example file shows all the properties that can be configured (though\nmost are commented out). It includes many comments to describe each\nproperty.\n\nThe YAML file must contain only a single-document. If it contains any\nunrecognized properties, the configuration will be rejected and the\ngateway will not start.\n\nThere are several top-level keys in the file, each of which contains\nproperties for a different category of configuration.\n1. **`listen`**: This section configures the listener for the gateway. This\n   contains details about the server like what interface to bind to, what\n   port to listen on, and whether TLS should be used.\n2. **`limits`**: This section configures limits, to aid with operations.\n3. **`backends`**: This section configures all of the backends to which the\n   gateway can send requests when processing a Knit query. This section\n   configures the available RPC services that can be used in a Knit query\n   and how to route them to backends. It includes connectivity details but\n   also details on how the gateway can access the schemata for the backend's\n   exposed RPC services.\n3. **`backend_tls`**: This section allows cross-cutting TLS configuration.\n   Each backend can be separately configured in the `backends` section\n   above. But if all or most backends use similar TLS configuration, it\n   can be consolidated in this top-level section. When there is configuration\n   in both this section and for a specific backend in `backends`, the values\n   in `backends` _override_ the values here. So this section effectively\n   defines the default TLS settings.\n4. **`descriptors`**: This section controls the polling behavior of the\n   gateway, for periodically reloading schemata. This allows the gateway\n   to reconfigure itself at runtime as the schemas change. The schemas\n   can also be cached, so a cached last-known-good schema can be used if\n   the source of the schema is otherwise unavailable when the gateway\n   starts up.\n5. **`cors`**: This section controls how the gateway handles cross-origin\n   requests and replies to CORS pre-flight requests.\n\nEach of the above config stanzas is described thoroughly in the sections below.\n\n## Listen Config\n\nThe top-level `listen` property is a _map_ with the following keys:\n\n- **`bind_address`**: The address on which to listen. This defaults to 0.0.0.0,\n  which means it will accept requests on _all_ network interfaces. You can\n  specify a specific address to limit what interfaces are used. For example,\n  setting this to 127.0.0.1 means that requests are only accepted on the\n  loopback interface (i.e. from the local host).\n- **`port`**: The port number on which to listen. There is no default: in order for\n  the gateway to use a TCP listener, a port must be configured. If the port is\n  configured as zero, an ephemeral port is used. In this case, the actual port\n  in use will be logged when the gateway starts.\n- **`unix_socket`**: The path to a Unix domain socket on which to listen. If the\n  socket file already exists, the gateway will not use it and will not start. There\n  is no default: in order for the gateway to listen on a Unix socket, this property\n  must be configured.\n- **`tls`**: If this section is present, the server will require clients to use\n  TLS (transport-level security, sometimes called SSL) when connecting. This means\n  that connections are secure: both parties can be authenticated via TLS certificates\n  and all traffic is encrypted.\n\n  This section is a map with the following sub-keys:\n  - **`cert`**: This is the path to a PEM-encoded X509 certificate. This is required\n    and configures the public key and certificate chain for the gateway's server\n    certificate.\n  - **`key`**: This is the path to a PEM-encoded X509 private key. This is required\n    and configures the private key for the gateway's server certificate.\n  - **`min_version`**: The minimum TLS version that the server will accept. This\n    defaults to 1.0. Other allowed settings are 1.1, 1.2, or 1.3.\n  - **`ciphers`**: The cipher suites to allow or disallow, for TLS 1.2 and below. (For\n    TLS 1.3, the supported cipher suites are not configurable and are always the\n    following: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256.)\n\n    This section is a map with possible keys of `allow` or `disallow`. Only one of these\n    keys may be present, depending on whether the configuration is using an allow-list of\n    cipher suites or a block-list. See [below](#tls-cipher-suites) for more details.\n  - **`client_certs`**: If this section is present, the gateway will request TLS certificates\n    from clients during the TLS handshake. This property is a map with the following allowed\n    keys which further control the gateway's behavior.\n    - **`require`**: If false or absent, client certs are verified if given, but are not\n      required. If true, connections will be terminated if the client does not provide a\n      valid cert.\n\n      When a client cert is present and valid, the authenticated identity (\"subject\" field\n      of the cert) will be added to HTTP headers for all requests to backends. It will be\n      set in a header named `Knit-Client-Subject` and will be in RFC 2253 Distinguished Names\n      syntax.\n    - **`cacert`**: This is the path to a PEM-encoded X509 certificate pool file that contains\n      certs for CAs (certificate authorities/issuers). These are used to verify client certs.\n\nThis property is required as the config _must_ define either a unix socket path or a\nport (or both).\n\n### TLS Cipher Suites\n\nTLS cipher suites can be configured in one of two ways:\n1. An allow-list is defined using the `allow` property. In this mode, only the suites\n   listed in the config will be allowed.\n2. A block-list is defined using the `disallow` property. In this mode, only the suites\n   listed in the config will be blocked, and all others will be allowed.\n\nThe following table shows all supported cipher suites. The table also shows which suites\nare allowed and disallowed by default, when no cipher suite configuration is provided,\n\n| Cipher Suite                                  | TLS Versions | Disposition |\n|-----------------------------------------------|--------------|-------------|\n| TLS_RSA_WITH_AES_128_CBC_SHA                  |              | Allowed     |\n| TLS_RSA_WITH_AES_256_CBC_SHA                  |              | Allowed     |\n| TLS_RSA_WITH_AES_128_GCM_SHA256               | TLS 1.2 only | Allowed     |\n| TLS_RSA_WITH_AES_256_GCM_SHA384               | TLS 1.2 only | Allowed     |\n| TLS_RSA_WITH_AES_256_GCM_SHA384               | TLS 1.2 only | Allowed     |\n| TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA          |              | Allowed     |\n| TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA          |              | Allowed     |\n| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA            |              | Allowed     |\n| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA            |              | Allowed     |\n| TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256       | TLS 1.2 only | Allowed     |\n| TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384       | TLS 1.2 only | Allowed     |\n| TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256         | TLS 1.2 only | Allowed     |\n| TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384         | TLS 1.2 only | Allowed     |\n| TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256   | TLS 1.2 only | Allowed     |\n| TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | TLS 1.2 only | Allowed     |\n| TLS_RSA_WITH_RC4_128_SHA                      |              | Disallowed  |\n| TLS_RSA_WITH_3DES_EDE_CBC_SHA                 |              | Disallowed  |\n| TLS_RSA_WITH_AES_128_CBC_SHA256               | TLS 1.2 only | Disallowed  |\n| TLS_ECDHE_ECDSA_WITH_RC4_128_SHA              |              | Disallowed  |\n| TLS_ECDHE_RSA_WITH_RC4_128_SHA                |              | Disallowed  |\n| TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA           |              | Disallowed  |\n| TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256       | TLS 1.2 only | Disallowed  |\n| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256         | TLS 1.2 only | Disallowed  |\n\n## Limits Config\n\nThe top-level `limits` property is a map. At the moment, there is just one key\nthat is allowed.\n\n- **`per_request_parallelism`**: Tte maximum parallelism per request. This is\n  the maximum number of concurrent RPCs that can be made on behalf of a single\n  Knit query.\n\n  If not specified, there is no limit, and all RPCs needed to evaluate a query\n  will all be made in parallel.\n\nAs other kinds of controls are implemented, configuration for them will be added\nto this section.\n\n## Backends Config\n\nThe top-level `backends` property is an _array_ of backend configuration maps. Each\nmap in the array has the following keys:\n\n- **`route_to`**: The base URL for this backend. This key must be provided.\n  The URL may use either \"http\" or \"https\" scheme. Note that no custom\n  TLS properties (such as custom root CA certificate or client certificates)\n  are currently supported for use with \"https\" URLs.\n- **`unix_socket`**: If the backend is listening on a Unix domain socket and\n  not a TCP socket, configure the path to the socket here. By default, TCP\n  connections are used, but when this property is present and non-empty it\n  is the path to a Unix socket that will be used instead.\n- **`h2c`**: If the `routeTo` property uses a plaintext \"http\" scheme, but\n  HTTP/2 should be used, set this property to true. It defaults to false.\n- **`protocol`**: This configured the protocol that will be used to communicate\n  with this backend. The default protocol is \"connect\". Other allowed options\n  are \"grpc\" or \"grpcweb\".\n- **`encoding`**: This configures the message encoding for sending requests to\n  this backend. The default is \"proto\", which uses the Protobuf binary format.\n  The other allowed option is \"json\".\n- **`services`**: This key is required. The value is a list of fully-qualified\n  service names that will be routed to this backend. If these services contain\n  methods that can resolve relations, then those relations are automatically\n  supported by the server.\n- **`tls`**: This key configures TLS settings for the backend. This key may\n  only appear when the `route_to` URL has a scheme of \"https\", indicating\n  secure connections are used. This property is a map whose contents are used\n  to configure a TLS client for successfully connecting to and verifying the\n  backend. See [below](#tls-client-config) for more details about the format\n  of this property.\n- **`descriptors`**: This key is required. This configuration indicates how\n  the gateway will find descriptors for the above named services. The value is\n  a map with the following keys, of which _only one may be set_:\n    - **`descriptor_set_file`**: The value for this key is the path to a file\n      that is an encoded [file descriptor set](https://github.com/protocolbuffers/protobuf/blob/v22.0/src/google/protobuf/descriptor.proto#L54-L58).\n      Both `buf` and `protoc` can produce such files. (See more [below](#descriptor-set-examples).)\n    - **`buf_module`**: The value for this key is the name of a module that has\n      been pushed to a Buf Schema Registry (BSR). The module name must be in the\n      format \"<remote>/<owner>/<repo>\". The first part defines the host name for\n      the BSR, for example `buf.build`. When using this option, you must provide\n      an environment variable named [`BUF_TOKEN`](https://docs.buf.build/bsr/authentication#buf_token)\n      that the gateway will use to authenticate with the BSR in order to download\n      the module's descriptors.\n    - **`grpc_reflection`**: The value for this key is a boolean. If true, then\n      the [gRPC Server Reflection](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md)\n      protocol will be used to download the descriptors from the\n      backend server itself.\n\n### TLS Client Config\n\nEach backend configured in the `backends` stanza can configure TLS client settings\nvia a `tls` property. Default TLS settings for all secure backends can be defined\nin the top-level `backend_tls` stanza. No TLS settings are required; reasonable\ndefaults will be used for all settings.\n\nThe property is a map with the following keys:\n\n- **`min_version`**: This minimum version of TLS to accept. Defaults to 1.2. Other\n  allowed values are 1.1, 1.2, and 1.3. Note that the default here is different than\n  for TLS _server_ settings, in the `tls` property of the [`listen`](#listen-config)\n  stanza. The listener default is more lenient, to support external clients that may\n  be using older browser or mobile OS software.\n- **`ciphers`**: The cipher suites to allow or disallow, for TLS 1.2 and below. (For\n  TLS 1.3, the supported cipher suites are not configurable and are always the\n  following: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256.)\n\n  This section is a map with possible keys of `allow` or `disallow`. Only one of these\n  keys may be present, depending on whether the configuration is using an allow-list of\n  cipher suites or a block-list. See [below](#tls-cipher-suites) for more details.\n- **`cacert`**: This is the path to a PEM-encoded X509 certificate pool file that\n  contains certs for CAs (certificate authorities/issuers). These are used to verify\n  server certs of the backends. If not present or blank, system defaults for the set\n  of trusted root CAs will be used.\n- **`skip_verify`**: This flag **disables** verification of server certs. Its use is\n  strongly discouraged. It is present primarily to aid with testing.\n- **`cert`**: This is the path to a PEM-encoded X509 certificate. This configures\n  the public key and certificate chain for the client certificate to use. This should\n  only be present if the server expects clients to provide a TLS certificate. If this\n  property is present, `key` must also be present.\n- **`key`**: This is the path to a PEM-encoded X509 private key. This configures\n  the private key for a client certificate to use. This should only be present if the\n  server expects clients to provide a TLS certificate. If this property is present,\n  `cert` must also be present.\n\n### Descriptor Set Examples\n\nIf using the `descriptor_set_file` option for the `descriptors` key, you can\nuse `buf` or `protoc` to generate a file in the correct format.\n\nThe following example uses `buf` to build proto sources in the current\ndirectory. The `-o` flag indicates the path to the output file that will\ncontain the descriptors:\n\n```shell\nbuf build . -o ../my-services.protoset\n```\n\nHere's another example using `buf`, this time to build the\n[buf.build/bufbuild/knit-demo](https://buf.build/bufbuild/knit-demo) module.\nThis module contains service definitions that describe the\n_Star Wars API_ ([swapi.dev](https://swapi.dev/)).\n\n```shell\nbuf build buf.build/bufbuild/knit-demo -o swapi.protoset\n```\n\nFinally, here's an example that uses `protoc`. This compiles a\nhypothetical file at path `foo/bar/services.proto`, where some of\nits imports are defined in a `../../others/proto` directory.\n\nHere too, the `-o` flag indicates the path to the output file that will\ncontain the descriptors. Most importantly, you must also include the\n`--include_imports` flag, or else the resulting file may be incomplete\nand unusable by the Knit gateway.\n\n```shell\nprotoc -I ../../others/proto foo/bar/services.proto \\\n    --include_imports -o ../my-services.protoset\n```\n\nNote that using `protoc` may involve specifying multiple input files\nand multiple `-I` include path options. Refer to your existing scripts\nthat invoke `protoc` for code generation.\n\n## Backend TLS Config\n\nThe top-level `backend_tls` property is a map that defines default TLS\nsettings. These settings are used with any backend with a secure URL\n(i.e. scheme is \"https\"). These settings may be overridden on a per-backend\nbasis via the `tls` property for that backend.\n\nThe allowed keys in this map are the same as for the `tls` property for a\nbackend, [as described above](#tls-client-config). There is one exception:\nthe `backend_tls` map may _not_ include a `server_name` key. An override\nserver name can only be configured on a per-backend basis and cannot be\nset in the defaults.\n\n## Descriptors Config\n\nThe top-level `descriptors` property is a map that defines default settings\nfor polling and caching of descriptors, which define the schemas for the\nsupported RPC services. It allows the following keys:\n\n- **`startup_max_wait_seconds`**: This is the maximum time to wait at startup\n  for schemas to be resolved and all descriptors to be downloaded. If it takes\n  longer than this to resolve schemas, the process will exit with an error\n  instead of continuing to wait.\n\n  If unset or zero, then a default value of 15 seconds is used.\n- **`polling_period_seconds`**: The time to wait in between attempts to\n  re-download descriptors. The gateway continually re-downloads schemas in case\n  they change over time.\n\n  If unset or set to zero, a default value of 15 minutes is used (which is 900\n  seconds).\n- **`polling_jitter`**: A value between zero and one for the amount of random\n  jitter to use when scheduling a polling attempt. This is used to prevent\n  multiple processes from inadvertently self-synchonizing and turning into a\n  thundering herd. A typical value for this purpose is 0.1 to 0.3.\n\n  A value of zero means no jitter. A value of 1 means 100% jitter, which means\n  the polling period can be perturbed up to 100% (so it could be as low as zero\n  as high as double the configured period). The default is 0.25.\n- **`polling_debounce_seconds`**: The number of seconds to wait after a schema\n  update to \"debounce\" updates from multiple sources.\n\n  A smaller value means the gateway's internals are re-created more frequently\n  when updates are frequent. A higher value can be more efficient as it re-creates\n  the internals only once for a sequence of rapid updates, but it may slow down\n  the reaction time from receiving a new schema and serving the corresponding new\n  configuration. Note that the server could benefit from debouncing even when the\n  polling period is high because there could be multiple sources of descriptors,\n  so multiple updates could be arriving, all from a single scheduled re-polling of\n  descriptors.\n\n  The default is zero, which is appropriate for development. But production\n  deployments with multiple schema sources should consider setting it to a value\n  to prevent too much CPU time being used by re-creating configuration. Between\n  5 ad 30 seconds is a reasonable range of values.\n- **`cache`**: This section configures a cache for resolved schemas. For Buf BSR\n  modules and gRPC reflection as descriptor sources, there is a possibility that\n  a network partition could prevent the gateway from downloading a schema at\n  startup. In this case, the cache can be used to fetch a last-known-good schema.\n  The cache is updated whenever a new schema is successfully downloaded. It is\n  used for loading the schemas if polling a backend source fails. This improves\n  resilience of the gateway.\n\n  Note that when loading schemas from local files, caching is not used. It is\n  assumed that the local file will be at least as reliable as a cache source, so\n  it's unnecessary.\n\n  This property is a map with three possible keys: `file_system`, `redis`, or\n  `memcache`. Only one of the three keys can be present since only a single\n  cache source can be active. See [here](#descriptor-caching) for more details\n  about configuring caches.\n\n### Descriptor Caching\n\nDescriptors that define the schemata of the gateway's supported RPC services\ncan be cached, to improve resilience in the face of a descriptor source being\nunavailable.\n\nThe `cache` property of the `descriptors` top-level key may contain one of\nthe following:\n\n- **`file_system`**: This caches the results on the file system. This is not\n  a particularly good fit if the gateway is deployed as a workload where the\n  storage is ephemeral (such that the cache will disappear when the workload\n  restarts). But if it is deployed with a persistent disk or has a network\n  filesystem mounted then this can work well. If the gateway workload will\n  be auto-scaled horizontally (e.g. more replicas created on demand), then\n  a network filesystem (where all replicas can share the files) works better\n  and is may be easier to configure than a persistent volume.\n\n  This property is a map that contains settings for caching via files.\n  - **`directory`**: This first property is required and has no default. You\n    must tell the gateway where to store cached data on the filesystem.\n  - **`file_name_prefix`**: This is a prefix used in names of files that\n    represent cache entries in the configured directory. The rest of the\n    filename is a cache key. The default prefix is `\"cache_\"`. The trailing\n    underscore is optional and will be automatically added if needed.\n  - **`file_extension`**: This is the extension of cache files created. The\n    default is `\".bin\"`. The leading dot is optional and will be automatically\n    added if needed.\n  - **`file_mode`**: The mode used to create the files. This will be combined\n    with the gateway process's _umask_ to determine the actual permissions of\n    created files. If unspecified or zero, defaults to 0600 (readable and\n    writable by owner). This value must be in octal; the leading zero is\n    optional.\n\n- **`redis`**:  This caches the results in a Redis server. Redis servers\n  typically are fast and have high up-time, making them suitable for use as\n  a distributed/shared cache.\n\n  This property is a map that contains settings for caching via Redis.\n  - **`host`**: The only required property is the address of the Redis host.\n    This should include both the host (domain name or IP address) and port.\n  - **`require_auth`**: If auth is required by the Redis server, set this to\n    true and also set `REDIS_USER` (optional) and `REDIS_PASSWORD` environment\n    variables. If only a `REDIS_PASSWORD` is provided, the gateway will issue\n    the `auth` command with only a password, for servers using the `requirepass`\n    configuration option. For servers using the Redis ACL system (as of Redis\n    6.0), both should be supplied.\n\n    This setting defaults to false.\n  - **`idle_timeout_seconds`**:  The idle timeout is used to close idle\n    connections before they are closed by the server. To that end, this should\n    be a value that is less than the server's timeout. If unspecified or zero,\n    idle connections will not be closed.\n  - **`database`**: If the gateway should store cache entries in a numbered\n    database, indicate the database number here. By default, no `select` command\n    is issued, so the default database (zero) is used.\n  - **`key_prefix`**: The key prefix can be used to namespace keys, in case other\n    workloads use the same Redis server to store data. The default value is empty.\n  - **`expiry_seconds`**: An expiry may be applied to each cache entry. The entry\n    will be auto-removed after this number of seconds elapses. By default, entries\n    will be created without expiry (and never be deleted).\n\n- **`memcache`**: This last option is for using memcached as a distributed/shared\n  cache. This is similar in many regards to using Redis.\n\n  This property is a map that contains settings for caching via memcached.\n  - **`hosts`**: This first value is the only required value. The value must be\n    an array of strings that define one or more hosts. If multiple hosts are\n    provided, the cache entries will be distributed across them. This allows\n    some cache entries to survive and be available, even if a single memcached\n    server instance becomes unavailable or is reset.\n  - **`key_prefix`**:  The key prefix can be used to namespace keys, in case other\n    workloads use the same memcached servers to store data. The default value is\n    empty.\n  - **`expiry_seconds`**:  An expiry may be applied to each cache entry. The entry\n    will be auto-removed after this number of seconds elapses. By default, entries\n    will be created without expiry (and never be deleted).\n\n## CORS Config\n\nThe top-level `cors` property is a map that defines default settings for how CORS\npre-flight requests are handled and what cross-origin requests are allowed. If\nthis section is not defined, all CORS pre-flight requests will get a negative\nresponse (i.e. origin not allowed). This section allows the following keys:\n\n- **`allowed_origins`**: This is an array of strings that define the list of\n  allowed origins. Specifying a wildcard `\"*\"` means all origins are allowed.\n  An entry in the list can include a single wildcard as a domain component. For\n  example, `\"https://*.foo.com\"` allows all immediate sub-domains of foo.com.\n  The default value is empty, which does not allow any origins.\n- **`allowed_headers`**:  This is a list of allowed headers. The special wildcard\n  entry `\"*\"` means all headers are allowed. The default value is empty, which\n  does not allow any headers.\n- **`allow_credentials`**: When true, the browser will be allowed to use\n  credentials (such as client TLS certs or cookies) with cross-origin requests.\n  The default value is false.\n- **`allow_private_networks`**:  When true, the browser will be allowed to send\n  cross-origin requests using a private network. The default value is false.\n- **`max_age_seconds`**: This value allows the browser to cache the results of a\n  pre-flight request, resulting in potentially fewer pre-flight requests to\n  authorize future cross-origin requests. If this field is omitted or zero, no\n  such header is sent to the browser. If not specified in a response header, the\n  default for browsers is typically 5 seconds.\n","readmeFilename":"README.md"}