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.ListServicesnames the registered backends andGateway.GetMethodSchemareturns a method's request and response schema.Gateway.Invokeforwards a request as serialized protobuf bytes.Gateway.InvokeJsontakes 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 withINVALID_ARGUMENT, naming the key and the message's fields; nothing is dropped.nullmeans 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 ownJsonParser/JsonFormatteron 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.Invokewith the encoded request.
- Requests name a field by its proto name (
- The gateway's gRPC server reflection serves its own descriptors merged with
each backend's, so a reflection client sees
virtufin.WorkManagernext tovirtufin.Gateway.FileContainingSymbolresolves every symbol kind, own or backend: services, methods, messages, fields, oneofs, enums and enum values. A registered name such asworkmanageralso 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.