← Ecosystem
12 Runtime
runtime-go
Go runtime engine and transport adapters for the universal Protobuf mesh.
Packages
runtime-go is a Go multi-module workspace — import only the modules you need
(the orm driver never pulls in go-ethereum, and vice-versa). Every package
carries a doc.go; this table is generated from those docs by tools/docgen
(make docs). See each package’s Go doc for how it works and example usage.
| Package | Import path | Summary |
|---|---|---|
agents | github.com/the-protobuf-project/runtime-go/agents | Package agents serves the protocols a model-driven client speaks to a service: build one Runtime, register the protocols it should answer, start it. |
agents/a2a | github.com/the-protobuf-project/runtime-go/agents/a2a | Package a2a serves an agent over the Agent2Agent protocol: the agent card that describes it, the transports it answers on, and the execution loop that turns a request into a stream of events. |
agents/mcp | github.com/the-protobuf-project/runtime-go/agents/mcp | Package mcp provides the Go runtime for the code protoc-gen-mcp generates: server configuration, transport handling, and MCP integration helpers. |
agents/shared | github.com/the-protobuf-project/runtime-go/agents/shared | Package shared holds what every protocol runtime in this module would otherwise copy. |
blockchain/evm | github.com/the-protobuf-project/runtime-go/blockchain/evm | Package evm implements the backend-agnostic store.Driver against an EVM chain, driving the Solidity storage contracts protorm generates. |
blockchain/fabric | github.com/the-protobuf-project/runtime-go/blockchain/fabric | Package fabric is a placeholder store.Driver for Hyperledger Fabric chaincode. |
cache | github.com/the-protobuf-project/runtime-go/cache | Package cache is the contract for runtime-go’s cache layer: the interfaces, and nothing that implements them. |
cache/core | github.com/the-protobuf-project/runtime-go/cache/core | Package core implements every cache strategy once, over a Driver. |
cache/dragonfly | github.com/the-protobuf-project/runtime-go/cache/dragonfly | Package dragonfly is the Dragonfly preset. |
cache/example | github.com/the-protobuf-project/runtime-go/cache/example | Command example runs the cache’s three steps — build a client, declare the cache, select a database — against every backend this module supports, and exercises all four strategies over each. |
cache/memcached | github.com/the-protobuf-project/runtime-go/cache/memcached | Package memcached is the memcached backend, and the argument for the driver split. |
cache/redis | github.com/the-protobuf-project/runtime-go/cache/redis | Package redis is the Redis preset. |
cache/resp | github.com/the-protobuf-project/runtime-go/cache/resp | Package resp is the driver for anything speaking the Redis serialization protocol: Redis itself, Dragonfly, Valkey, KeyDB. |
cache/shared | github.com/the-protobuf-project/runtime-go/cache/shared | Package shared holds the telemetry this module’s code logs and measures through. |
database | github.com/the-protobuf-project/runtime-go/database | Package database stores Go structs in whichever backend you point it at. |
database/arangodb | github.com/the-protobuf-project/runtime-go/database/arangodb | Package arangodb implements the backend-agnostic store.Driver over ArangoDB, and the graph capability alongside it. |
database/cached | github.com/the-protobuf-project/runtime-go/database/cached | Package cached puts a read-through cache in front of any store.Driver, so a record read repeatedly is fetched from the backing store once. |
database/core | github.com/the-protobuf-project/runtime-go/database/core | Package core is the code every store driver would otherwise copy. |
database/examples/simple/mongodb | github.com/the-protobuf-project/runtime-go/database/examples/simple/mongodb | Command mongodb stores Go structs in MongoDB. |
database/examples/simple/sql | github.com/the-protobuf-project/runtime-go/database/examples/simple/sql | Command sql stores the same struct in a relational database. |
database/examples/simple/timescale | github.com/the-protobuf-project/runtime-go/database/examples/simple/timescale | Command timescale stores Go structs as time-series data. |
database/examples/store/cached | github.com/the-protobuf-project/runtime-go/database/examples/store/cached | Command cached puts a read-through cache in front of a store. |
database/examples/store/document | github.com/the-protobuf-project/runtime-go/database/examples/store/document | Command document stores records in MongoDB and watches them change. |
database/examples/store/graph | github.com/the-protobuf-project/runtime-go/database/examples/store/graph | Command graph stores records and the connections between them. |
database/examples/store/internal/model | github.com/the-protobuf-project/runtime-go/database/examples/store/internal/model | Package model builds the resource descriptors the examples store. |
database/examples/store/keyvalue | github.com/the-protobuf-project/runtime-go/database/examples/store/keyvalue | Command keyvalue stores records in Redis. |
database/examples/store/sql | github.com/the-protobuf-project/runtime-go/database/examples/store/sql | Command sql stores records in a relational database. |
database/examples/store/timeseries | github.com/the-protobuf-project/runtime-go/database/examples/store/timeseries | Command timeseries partitions a resource by time and reduces over it. |
database/mongodb | github.com/the-protobuf-project/runtime-go/database/mongodb | Package mongodb implements the backend-agnostic store.Driver over MongoDB. |
database/orm | github.com/the-protobuf-project/runtime-go/database/orm | Package orm implements the backend-agnostic store.Driver over GORM. |
database/redis | github.com/the-protobuf-project/runtime-go/database/redis | Package redis implements the backend-agnostic store.Driver over Redis: durable records addressed by a store.Resource’s primary key, stored as proto wire format, with a set of keys alongside so they can be listed. |
database/store | github.com/the-protobuf-project/runtime-go/database/store | Package store is the backend-agnostic core of the runtime data layer: a single CRUD Driver contract that operates on proto messages, a Resource descriptor that mirrors protorm’s IR at runtime, and a reflection bridge every driver reuses to move values between a proto message and a backend column map. |
database/timescale | github.com/the-protobuf-project/runtime-go/database/timescale | Package timescale implements the time-series half of the database contract over TimescaleDB. |
grpc | github.com/the-protobuf-project/runtime-go/grpc | Package grpc provides HybridServer — a single server that simultaneously speaks gRPC, HTTP/1.1 JSON gateway (via grpc-gateway), optional HTTP/3 (QUIC), an MCP (Model Context Protocol) endpoint, and an A2A (Agent2Agent) endpoint, all sharing the same port and TLS configuration. |
grpc/options | github.com/the-protobuf-project/runtime-go/grpc/options | Package options holds the configuration for the grpc HybridServer: service identity (name, description, version), the gRPC/HTTP/MCP endpoints, the environment mode, the health/HTTP-3 toggles, and the OpenTelemetry metric selection. |
grpc/shared | github.com/the-protobuf-project/runtime-go/grpc/shared | Package shared holds the process-wide singletons the grpc server initializes once and tears down on exit — currently the Pulse observability client ([Pulse]), constructed in an init with the service identity, log level, and tracing enabled. |
interfaces/adapter | github.com/the-protobuf-project/runtime-go/interfaces/adapter | Package adapter is the generic gRPC layer between a protorm-generated service and a store.Driver. |
network | github.com/the-protobuf-project/runtime-go/network | Package network provides GraphQL, HTTP, and WebSocket clients behind a single factory (NewConnection) with consistent connection options and optional connectivity verification. |
network/examples/graphql | github.com/the-protobuf-project/runtime-go/network/examples/graphql | Command graphql is a runnable example of using the network package’s GraphQL client to issue queries, mutations, and subscriptions against an endpoint. |
network/examples/http | github.com/the-protobuf-project/runtime-go/network/examples/http | Command http is a runnable example of using the network package’s HTTP client to perform GET, POST, and other requests with retries and context support. |
network/examples/websocket | github.com/the-protobuf-project/runtime-go/network/examples/websocket | Command websocket is a runnable example of using the network package’s WebSocket client for full-duplex Send/Receive with auto-reconnect and keepalive. |
network/graphql | github.com/the-protobuf-project/runtime-go/network/graphql | Package graphql provides small helpers and scalar types for generated GraphQL clients: pointer constructors for optional (nullable) arguments, and scalar types that tolerate engine-specific JSON encodings. |
network/runtime | github.com/the-protobuf-project/runtime-go/network/runtime | Package runtime is the stable, single-import facade that generated GraphQL clients depend on. |
observability | github.com/the-protobuf-project/runtime-go/observability | Package observability wires runtime-go modules to the opentelementry SDK. |
streams | github.com/the-protobuf-project/runtime-go/streams | Package streams defines the backend-agnostic contract for runtime-go’s messaging layer. |
streams/codec/protobuf | github.com/the-protobuf-project/runtime-go/streams/codec/protobuf | Package protobuf encodes stream payloads as protocol buffers. |
streams/core | github.com/the-protobuf-project/runtime-go/streams/core | Package core is the code every streams provider would otherwise copy. |
streams/examples/kafka | github.com/the-protobuf-project/runtime-go/streams/examples/kafka | Command kafka demonstrates the streams contract over Apache Kafka. |
streams/examples/mqtt | github.com/the-protobuf-project/runtime-go/streams/examples/mqtt | Command mqtt demonstrates the streams contract over MQTT 5. |
streams/examples/nats | github.com/the-protobuf-project/runtime-go/streams/examples/nats | Command nats demonstrates the streams contract over NATS, in both forms, against a live server. |
streams/examples/rabbitmq | github.com/the-protobuf-project/runtime-go/streams/examples/rabbitmq | Command rabbitmq demonstrates the streams contract over RabbitMQ. |
streams/examples/redis | github.com/the-protobuf-project/runtime-go/streams/examples/redis | Command redis demonstrates the streams contract in all three of the Redis provider’s delivery modes, against a live Redis. |
streams/examples/zeromq | github.com/the-protobuf-project/runtime-go/streams/examples/zeromq | Command zeromq demonstrates the streams contract over ZeroMQ PUB/SUB. |
streams/kafka | github.com/the-protobuf-project/runtime-go/streams/kafka | Package kafka delivers streams over Apache Kafka. |
streams/mqtt | github.com/the-protobuf-project/runtime-go/streams/mqtt | Package mqtt delivers streams over MQTT 5. |
streams/nats | github.com/the-protobuf-project/runtime-go/streams/nats | Package nats delivers streams over NATS, in two forms. |
streams/rabbitmq | github.com/the-protobuf-project/runtime-go/streams/rabbitmq | Package rabbitmq delivers streams over RabbitMQ. |
streams/redis | github.com/the-protobuf-project/runtime-go/streams/redis | Package redis implements streams.Streams over Redis. |
streams/shared | github.com/the-protobuf-project/runtime-go/streams/shared | Package shared holds the telemetry this module’s code logs and measures through. |
streams/zeromq | github.com/the-protobuf-project/runtime-go/streams/zeromq | Package zeromq delivers streams over ZeroMQ PUB/SUB. |
telemetry | github.com/the-protobuf-project/runtime-go/telemetry | Package telemetry defines the backend-agnostic Meter contract that generated and hand-written code instruments against. |
ulid | github.com/the-protobuf-project/runtime-go/ulid | Package ulid generates sortable, collision-resistant identifiers for runtime-go modules. |
network/examples/graphql/server | server | Command server is a minimal GraphQL server used by the GraphQL client example; it serves a generated schema so the example queries, mutations, and subscriptions have a live endpoint to run against. |
Contributing
Issues and pull requests are welcome. Please open an issue before submitting a large change so we can discuss the approach first.
License
Apache 2.0 — see LICENSE.
© 2026 the-protobuf-project