2 Gates
Anton Nesterov edited this page 2026-11-08 20:25:29 +01:00

Gates

A gate is a named HTTP endpoint that forwards requests to one fixed target (an HTTP URL or a plugin function) behind the platform's authentication and an optional per-gate access rule. Gates are how you expose one specific thing (a plugin function, an internal service) to some set of callers without handing out broad API keys.

Gates are global (they live in the default database) and are managed as records; calling one is a single stable URL.

Quick start

# once, as admin: expose a plugin function through a gate
curl -X POST "$VSKI_URL/api/collections/_gates/records" \
  -H "X-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "tagger-invoke",
    "url": "plugin://tagger/on_photo",
    "rules": "*"
  }'

# any authenticated caller the rule allows can now call it; the body is
# the function's params:
curl -X POST "$VSKI_URL/api/gates/tagger-invoke" \
  -H "X-API-Key: $VIEWER_KEY" -H "Content-Type: application/json" \
  -d '{"id": "1", "image": "a.jpg"}'

The SDKs wrap the call side:

result = client.gate("tagger-invoke", {"id": "1", "image": "a.jpg"})

and in TypeScript:

const result = await client.gate("tagger-invoke", { id: "1", image: "a.jpg" });

Managing gates

Gates are records of the _gates system collection (admin only; the system collection has empty default rules, which deny non-admins). The web console has a dedicated page under Settings → API Gates.

field meaning
name unique; used in the route /api/gates/{name}
url the fixed target: an http(s):// URL, or plugin://<instance>/<function>
rules access rule: null/"*" = any authenticated caller, "" = admins only, or a rule expression
headers JSON-encoded string map of headers set on proxied HTTP requests (incoming values are overridden)
method documentation only: the caller's HTTP method is always forwarded, this field does not restrict it
description free text
# list / update / delete like any collection record
curl "$VSKI_URL/api/collections/_gates/records" -H "X-API-Key: $ADMIN_KEY"
curl -X PATCH "$VSKI_URL/api/collections/_gates/records/<id>" \
  -H "X-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
  -d "{\"rules\": \"'editors' in @request.auth.roles\"}"

Calling a gate

Routes: GET/POST/PUT/DELETE/PATCH /api/gates/{name}, behind the global auth middleware: every caller must present an API key or a token (anonymous requests get 401 before the gate is even looked up).

The gate's rule is then evaluated with the caller's identity, e.g. @request.auth.id = 'u_123' or 'editors' in @request.auth.roles, the same expression syntax as collection rules (see Rules and Access Control); admins bypass rules. Request data is not available to gate rules. A denied caller gets 403.

Everything else depends on the target type.

HTTP targets (http:// / https://)

The gate acts as a reverse proxy:

  • The caller's method and raw body are forwarded verbatim to the fixed URL. Query parameters are not forwarded; anything the target needs must be baked into the gate's URL.
  • Incoming headers are copied (minus host/connection/ content-length/transfer-encoding), then the gate's headers map is applied on top. This is how a gate injects a credential an upstream service expects without callers ever seeing it.
  • The upstream's status code and headers are passed through; the body is fully buffered and returned with Content-Type: application/json.
  • There is no timeout and no retry: a slow upstream holds the caller connection open indefinitely. There is also no streaming: a gate cannot carry SSE or chunked responses.
  • Per-gate call statistics are recorded under the stats collection gate:<name>.

Plugin targets (plugin://<instance>/<function>)

A plugin target dispatches the call over the warm plugin pipe: no HTTP hop, no credentials to inject:

  • The caller's JSON body becomes the function's params (it must be a JSON object; an empty body is an empty object).
  • The function's return value comes back verbatim as the response body.
  • The function identity is fixed by the gate record: callers pick the payload, never the function. This is the important security property: a caller you allow through the rule can do exactly one thing.
  • The instance must be running (502 otherwise, with the reason).
  • The call rides the standard plugin invoke budget (30 s default, 120 s hard cap). Work longer than that belongs in a pipeline, not a gate.
  • The database the instance is looked up in comes from the caller's x-dbname header (default default).

Prefer plugin:// targets over the HTTP bridge. Pointing a gate at the server's own POST /api/plugin-instances/{name}/invoke route with an injected admin key also works, but there the caller's body selects the function; anyone passing the rule can invoke any function on that instance with admin authority. plugin:// targets exist to close exactly that hole. (The bridge remains useful for servers that predate plugin targets.)

Security notes

  • Only admins can create, list, update or delete gates.
  • rules is the only per-gate access control; there are no per-gate rate limits or quotas. A gate named rules: "*" is reachable by every authenticated principal; use a rule expression to narrow it.
  • An HTTP gate's url is arbitrary: admins can point it at internal services (that is the feature), so treat gate-creation rights as sensitive as the credentials a gate can inject.
  • Gates buffer whole request and response bodies; do not route large payloads through them.

Stats

Every gate call records a hit under gate:<name> (status and duration), visible in the SQL console / stats views like any _stats_* collection.

See also