Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.faremeter.xyz/llms.txt

Use this file to discover all available pages before exploring further.

@faremeter/gateway-nginx is the OSS package that lets a marketplace operator turn an OpenAPI spec into a working payment-enforcing nginx configuration. It is what the marketplace API nodes use under the hood. Most readers do not need to install it — but it helps to know what it does, because it shapes what publishers can express in their pricing. Package: @faremeter/gateway-nginx

​
What it does

The gateway SDK takes a parsed OpenAPI spec (with x-faremeter-* extensions) and emits two things:
  • nginx location blocks — included by the operator inside their own server { } block. Each priced endpoint gets a Lua-instrumented location.
  • A bundled Lua module (faremeter.lua) — referenced by the location blocks at runtime to talk to a sidecar process that evaluates pricing and validates payment.
import { generateConfig } from "@faremeter/gateway-nginx";

const { locationsConf, luaFiles, warnings } = generateConfig(input);
// locationsConf: string of nginx location blocks
// luaFiles: { "faremeter.lua": "..." }
generateConfig is a pure function — no I/O, no network — so it is safe to call in tests or build pipelines.

​
How it fits

                                +-----------+
                                |  sidecar  |   evaluates pricing,
                                +-----------+   talks to facilitator
                                  ^   |
                         /request |   | JSON
                        /response |   v
+--------+    +-------------------+----------+    +-----------+
| client | -> |       nginx (OpenResty)      | -> | upstream  |
+--------+ <- |   Lua hooks the request,     | <- | (publisher|
              |   reads payment, forwards    |    |  backend) |
              |   to upstream when paid      |    +-----------+
              +------------------------------+
The Lua code generated by the SDK is stateless — all pricing decisions are made in the sidecar. The sidecar is the only component that imports @faremeter/middleware and the payment evaluator. nginx itself never imports Faremeter code; it just speaks HTTP/JSON to the sidecar via Unix socket. For the full nginx phase model (access_by_lua_block, header_filter_by_lua_block, body_filter_by_lua_block, log_by_lua_block), see the package’s ARCHITECTURE.md.

​
Capabilities a publisher can use

The pricing extensions in your OpenAPI spec map to features the SDK supports:
  • Three transports — HTTP JSON, Server-Sent Events (SSE) streaming, and WebSocket frame relay. The transport is detected from the response and handled appropriately.
  • Method dispatch — different pricing for GET vs POST on the same path.
  • Response field capture — pricing can depend on response data (e.g. usage.total_tokens from an LLM response). The generator statically analyzes the spec and only parses chunks that could contain referenced fields.
  • Optional spec hosting — serve the OpenAPI spec at /.well-known/openapi.yaml for discovery clients.
Static analysis means the generated config only does the work it needs to: an endpoint with a fixed price never inspects the response body.

​
Prerequisites for operators

The generated config requires OpenResty (nginx + LuaJIT) and the lua-resty-http module. The operator runs OpenResty, includes the generated locationsConf, and runs the sidecar process.

​
Gateway-mode vs legacy

Gateway-mode (the path described above) is the current and recommended way to enforce payment at the proxy. The marketplace repo also contains a hand-written Lua access module from earlier work; new tenants should be on gateway-mode and existing tenants are being migrated.

​
What’s next

Publisher path

Where the OpenAPI spec the SDK consumes comes from.

Self-hosting

Run the SDK inside your own marketplace deployment.

Facilitators

What the sidecar talks to when validating and settling payment.

Package on GitHub

README, ARCHITECTURE.md, and source.