Skip to content

Calling the gateway

The gateway speaks native gRPC on its gRPC port (5002) and gRPC-Web on its HTTP port (5001), for browsers. The HTTP port also answers the Kubernetes /health, /healthz and /ready probes; every business operation is a gRPC call.

Clients

Use the generated clients: C#, Python or TypeScript. They cover the gateway's own services (Gateway, Config, State, Pubsub, Trigger) and reach the backends registered with it, such as workmanager.

Backends known only by reflection

  • Gateway.ListServices names the registered backends and Gateway.GetMethodSchema returns a method's request and response schema.
  • Gateway.Invoke forwards a request as serialized protobuf bytes.
  • Gateway.InvokeJson takes and returns JSON strings inside the gRPC message; the gateway converts them to and from protobuf with the backend's reflected descriptors, following the protobuf JSON mapping:
    • Requests name a field by its proto name (code_source) or its JSON name (codeSource). A key that names no field, or two members of one oneof, is refused with INVALID_ARGUMENT, naming the key and the message's fields; nothing is dropped. null means the field's default. 64-bit integers may be numbers or strings, enums names or numbers, bytes standard or URL-safe base64. The well-known types take their JSON forms: Timestamp "2026-11-15T21:30:00Z", Duration "1.5s", FieldMask "fooBar,baz", the wrappers as bare values, Struct/Value/ListValue as JSON, Any as {"@type": "type.googleapis.com/…", …}.
    • Responses use the proto field names (code_url) and include default values ("", 0, []; a message field only when set). 64-bit integers are strings, enums names, bytes base64, the well-known types in their JSON forms.
    • The mapping (ProtoJson) is checked in CI against Google.Protobuf's own JsonParser/JsonFormatter on Google's conformance schema (ProtoJsonConformanceTests). It deliberately differs in two places: it accepts URL-safe base64 (the mapping allows it, the C# parser does not), and it refuses an Any without "@type" (the C# parser reads it as an empty Any, dropping its content).
    • Clients that have the backend's generated types (the web app with @virtufin/workmanager) can skip JSON altogether: Gateway.Invoke with the encoded request.
  • The gateway's gRPC server reflection serves its own descriptors merged with each backend's, so a reflection client sees virtufin.WorkManager next to virtufin.Gateway. FileContainingSymbol resolves every symbol kind, own or backend: services, methods, messages, fields, oneofs, enums and enum values. A registered name such as workmanager also resolves as an alias.

Command line and browser

# List and describe services through the gateway
grpcurl -plaintext localhost:5002 list
grpcurl -plaintext localhost:5002 describe virtufin.WorkManager
grpcurl -plaintext localhost:5002 describe virtufin.WorkManager.ListWorkers
grpcurl -plaintext localhost:5002 describe virtufin.ListWorkersRequest

# Invoke a backend method with JSON over gRPC
grpcurl -plaintext -d '{"service":"workmanager","method":"ListWorkers","request_data":"{}"}' \
  localhost:5002 virtufin.Gateway/InvokeJson

For a remote endpoint, drop -plaintext and pass the key with -H "x-api-key: $VIRTUFIN_API_KEY".

For an interactive explorer, run grpcui -plaintext localhost:5002 (or bash common/scripts/run_grpcui_local.sh localhost:5002; TLS=true for a remote TLS endpoint). Keep it loopback-only; see the gRPC API explorer guide.