`grpc://`¶

gRPC producer + server. Built on google.golang.org/grpc. Reflection-style dispatch — the route ships raw (already-marshaled) []byte payloads, so no .proto compilation is required.

URI shape¶

grpc://host:port/<serviceFQN>?method=<m>&negotiationType=PLAINTEXT|TLS|INSECURE

serviceFQN is the fully-qualified gRPC service name (e.g. echo.EchoService). The method comes from the URI's method param or the HelixGrpcMethodName exchange header (per-request override).

Parameters¶

Common¶

Param	Type	Default	Description
`host`	string	from URI	gRPC host.
`port`	integer	from URI	gRPC port.
`service`	string	from URI	Service FQN.
`flowControlWindow`	integer	`1048576`	HTTP/2 connection flow-control window.
`maxMessageSize`	integer	`4194304`	Max bytes per send/recv message.

Consumer (server)¶

Param	Type	Default	Description
`initialFlowControlWindow`	integer	`1048576`	HTTP/2 per-stream initial window.
`keepAliveTime`	duration	`2h`	Ping interval when idle.
`keepAliveTimeout`	duration	`20s`	Ping-reply timeout.
`maxConcurrentCallsPerConnection`	integer	`2147483647`	Max in-flight streams per HTTP/2 connection.
`maxConnectionAge`	duration	—	Kill connection after this duration.
`maxConnectionAgeGrace`	duration	—	Grace after `maxConnectionAge`.
`maxConnectionIdle`	duration	—	Kill after idle this long.
`maxInboundMetadataSize`	integer	`8192`	Max bytes of inbound metadata headers.
`permitKeepAliveTime`	duration	`5m`	Minimum keep-alive interval the server allows from clients.
`permitKeepAliveWithoutCalls`	boolean	`false`	Allow keep-alives with no active streams.
`forwardOnCompleted`	boolean	`false`	Emit a synthetic Exchange with `HelixGrpcEventType=onCompleted` when a stream ends.
`forwardOnError`	boolean	`false`	Emit a synthetic Exchange with `HelixGrpcEventType=onError` when a stream fails.

Producer (client)¶

Param	Type	Default	Description
`method`	string	—	gRPC method name. Per-request override via `HelixGrpcMethodName` header.
`userAgent`	string	`helix-grpc/1.0`	gRPC `User-Agent`.

Security¶

Param	Type	Default	Description
`negotiationType`	enum	`PLAINTEXT`	`PLAINTEXT` / `TLS` / `INSECURE` (TLS + skip-verify).
`keyCertChainResource`	string	—	Path to client/server certificate file.
`keyResource`	string	—	Path to private key file.
`trustCertCollectionResource`	string	—	Path to CA bundle (RootCAs / ClientCAs).
`authenticationType`	enum	`NONE`	`NONE` / `JWT`.
`jwtAlgorithm`	enum	`HMAC256`	`HMAC256/384/512` or `RS256/384/512`.
`jwtSecret`	string	—	HMAC shared secret (`HMAC`) or path to PEM-encoded RSA key (`RS`).
`jwtIssuer` / `jwtSubject`	string	—	`iss` / `sub` JWT claims.

Headers¶

Header	Direction
`HelixGrpcMethodName`	Both (per-request method override; written by consumer)
`HelixGrpcUserAgent`	Read
`HelixGrpcEventType`	Written by consumer for stream events (`onNext`, `onCompleted`, `onError`)
`HelixGrpcMetadata`	Both (gRPC metadata; `map[string]string`)

YAML examples¶

workflows:
  # 1. Unary client — call a remote echo service.
  - id: grpc-unary
    description: Call EchoService.Unary on a remote gRPC server.
    trigger:
      uri: direct://invoke-grpc
    steps:
      - to: grpc://api.example.com:50051/echo.EchoService?method=Unary&userAgent=helix/1.0

  # 2. Client with TLS + JWT auth.
  - id: grpc-secure
    description: TLS connection with JWT bearer auth.
    trigger:
      uri: direct://invoke-secure
    steps:
      - to: grpc://api.example.com:50051/echo.EchoService
        params:
          method: Unary
          negotiationType: TLS
          trustCertCollectionResource: /etc/ssl/certs/ca.crt
          authenticationType: JWT
          jwtAlgorithm: HMAC256
          jwtSecret: shared-secret
          jwtIssuer: helix
          jwtSubject: alice

  # 3. Server — accept inbound gRPC calls.
  - id: grpc-server
    description: Accept inbound gRPC calls on this host:port.
    trigger:
      uri: grpc://0.0.0.0:50051/echo.EchoService
      params:
        forwardOnCompleted: "true"
        forwardOnError: "true"
        keepAliveTime: "60s"
        maxMessageSize: "8388608"
    steps:
      - log:
          message: "method=${headers.HelixGrpcMethodName} event=${headers.HelixGrpcEventType}"
      - transform:
          starlang: '"echo:" ++ str(body())'

  # 4. Per-message method override via header.
  - id: grpc-dynamic-method
    description: Method comes from the exchange header.
    trigger:
      uri: direct://variable-method
    steps:
      - set-header:
          name: HelixGrpcMethodName
          starlang: headers["target_method"]
      - to: grpc://api.example.com:50051/echo.EchoService

grpc://¶