Introduction

Imagine a control plane that needs to talk continuously with agents installed on several hosts. The API sends commands, each agent publishes heartbeats (periodic signals that it is still alive), reports inventory changes and can open an interactive channel for a terminal. A sequence of independent HTTP calls would still work for one-off operations, but it would not express this persistent two-way flow as naturally. This is the kind of problem where gRPC in .NET 10 deserves consideration.

gRPC is a remote procedure call (RPC) framework: the client invokes methods defined by a contract on a server, using typed messages that are usually serialized with Protocol Buffers and carried over HTTP/2. I would choose it when the participants are services under the control of the same team and need to share generated contracts or maintain a continuous message flow, especially a bidirectional one. That does not make gRPC a universal replacement for REST, nor does it prove that it will be faster for every application.

In Dokpod, the browser uses REST/OpenAPI for interface operations and SignalR for notifications. gRPC lives in the internal channel between the API and the agents: the agent opens an outbound connection, authenticates with a client certificate and keeps a stream open to exchange control messages. That choice answers a concrete need of the system, not a rule for every product.

This is the first of three articles in the APIs and Communication in .NET series. Part 2 will be an introductory GraphQL guide; part 3 will explain SignalR in .NET, from the first Hub to production. Neither had been published when this article was written, so I do not include links that did not exist yet.

ℹ️ Info: At the time of this review, the public Dokpod repository had no published releases or tags. The code links in this article point to the main branch and follow its current state; they may change and do not represent a stable release.

RPC, REST and the role of HTTP/2

An RPC call starts with a familiar question: “which operation do I want to execute and which message do I need to send?”. A client calls a method such as GetInventory; the server receives the data, executes the operation and returns a response. The network is hidden behind an interface that looks like a local call, but the operation is still remote: it can be slow, fail, be cancelled or lose the connection. That distinction matters because a network does not offer the same guarantees as an in-process call.

For an RPC to exist, client and server need to agree on the method name, the input and output types and how the data will be represented. That agreement is the contract. In gRPC, it is usually described in .proto files; tools generate code to build messages and invoke the service. The code reduces typing differences and helps detect incompatibilities at build time, but it does not remove the need to version and deploy both sides carefully.

REST starts from a different mental model. Instead of asking “which remote method do I call?”, the client interacts with resources identified by URLs and uses HTTP semantics such as GET, POST, PUT and DELETE. A REST API usually exposes representations, commonly JSON, that can be inspected and consumed by a variety of clients. gRPC describes operations and messages more rigidly and usually favors clients that know the contract and can use generated code. It is not an absolute split: both can carry structured data and both depend on careful design decisions.

Traditional gRPC uses HTTP/2. That version of HTTP organizes messages into frames and allows several streams to be multiplexed over one connection. Multiplexing means that different exchanges can share the connection without opening a TCP connection for each call. HTTP/2 also defines flow control to limit how much data a receiver accepts. Those features provide a suitable foundation for persistent calls, but they do not automatically make an application faster: serialization, message size, network, load balancing, concurrency and server work still determine the result.

A gRPC stream is a logical call that can contain one message or many. It should not be confused with “one TCP connection per method”, nor should you assume that a connection can stay open forever on any infrastructure. Proxies, firewalls, NATs, duration limits, certificates and restarts can interrupt the flow. The application needs to decide how to detect the drop, open another session and recover the state that became uncertain.

There is also a practical consequence: a traditional gRPC client in the browser is not the same as a C# or Go client. Browsers do not give unrestricted access to the HTTP/2 primitives that conventional gRPC expects. For web scenarios there are gRPC-Web and gateways that translate protocols, but they add components and restrictions. In Dokpod, the interface uses HTTP and SignalR, while the agents use gRPC; separating the consumers avoids forcing the browser to speak the internal protocol.

⚠️ Warning: HTTP/2 multiplexes streams, but the connection is still subject to network failures and limits. Treat every disconnection as a normal part of the design, not as an impossible event.

Protocol Buffers, .proto files and generated code

Protocol Buffers, or Protobuf, is a serialization format and a language for describing messages. Serializing means turning a structure into bytes to transmit or store it; deserializing means rebuilding the structure on the other side. A .proto file declares messages, fields, field numbers, services and methods. From it, the compiler and the language plugins generate types for the client and the server.

A field has a type, a name and a number. The name helps the people reading the contract; the number identifies the field in the binary format. That difference is fundamental: once published and used, a number must not be reused for another meaning. If a field is removed, reserve its number and, when appropriate, its name. Adding optional fields is usually compatible in the binary format, but that does not guarantee behavioral compatibility. An old agent can ignore a new field; business code, however, may depend on a capability (an advertised feature) that the agent does not offer.

It is also important to separate wire format compatibility (the transmitted format) from application compatibility. A change can still be decoded and yet break a switch, a validation or a business rule. A deployment can involve several versions of the API and agents running at the same time. So contract changes need a rollout strategy, tests with consecutive versions and enough observability to identify who still uses the old format.

In Dokpod, AgentControl declares two streaming methods. Connect receives messages from the agent and returns messages from the control plane. Exec uses another, separate stream for terminal frames. Envelope messages carry metadata such as the protocol version, the session identifier, the fencing token and the sequence. A oneof groups alternative payload types, such as AgentHello, Heartbeat, an inventory page or a command. That gives the reader an explicit view of the possible messages without turning the channel into a generic proxy to the engine API.

The contract also records reserved fields and evolution comments. For example, inventory messages have revisions and pages, and new capabilities are accepted only when the server recognizes them. That discipline is part of the cost of a custom protocol: the team becomes responsible for documenting, testing and evolving the contracts the product uses.

The four gRPC call types

The type of an RPC is defined by the number of messages each side can send during the call. The unary method receives one message and returns one message. It is the simplest model: fetching the details of a configuration, validating a token or looking up a single piece of information. It resembles an HTTP request/response call, although it uses a method and messages typed in the contract.

In server streaming, the client sends one request and the server responds with zero or more messages over time. A paginated export, a progress sequence or continuous updates that do not need a client response are possible examples. The client can cancel the stream, and the server must propagate the cancellation token to the asynchronous work. If the server tries to send an infinite response without limits, the resource cost can be continuous as well.

In client streaming, the client sends several messages and receives one final response. That can make sense for sending batches, fragments of a task or samples that the server consolidates. The server reads until the client closes the stream and then responds. This pattern is not just “many unary calls”: it keeps one call open and an ordered sequence of messages.

In bidirectional streaming, or duplex, both sides can send several messages during the same call. They do not need to alternate one message per side: client and server can read and write independently. It is useful when there is a continuous exchange of commands, responses, states and acknowledgements. The application protocol still has to define correlation, ordering, flow control, priority and what to do when the call ends.

ModeClient messagesServer messagesExample use
UnaryOneOneOne-off lookup
Server streamingOneManyProgress or read feed
Client streamingManyOneSending batches for consolidation
BidirectionalManyManyInteractive control channel

Dokpod’s Connect is bidirectional because the agents and the API need to send messages while the session is active. That does not mean every agent needs to transmit data at every moment. Heartbeats, inventory and commands are application messages carried on the stream; the application still defines when and why each one should flow.

Why Dokpod chose gRPC for the agents

Dokpod’s context is different from a public API aimed at any browser. The product needs to reach container engines installed on hosts that may be on private networks, behind NAT or protected by rules that do not allow connections initiated from outside. Having the central API initiate a connection to each host would require reachable addresses and network rules per environment.

With an outbound connection, the agent initiates the session to the API. That usually fits restricted networks better because the host only needs to allow controlled egress, not publish the Docker socket, a Podman endpoint or SSH to the network. The pattern does not remove network configuration or every threat, but it reduces the need to open the engine’s administrative interface to remote connections.

The second reason is the domain contract. A generic proxy that forwarded any call to the Docker Engine would widen the impact of an authorization failure: the API could become a bridge to arbitrary host operations. Dokpod sends its own versioned commands, such as starting or stopping a container, and the agent validates what it received before using the engine adapter. That limits the surface compared with an unrestricted proxy. Even so, the agent is a privileged component; the protocol needs to authorize each operation, validate inputs and avoid exposing sensitive data.

Bidirectional streaming lets the server send commands and the agent report acceptance, result, heartbeat and inventory differences on the same control channel. The choice also lets the server negotiate session, version and capabilities. That is valuable for a product that controls both ends, but it carries the cost of maintaining a specification and guaranteeing compatibility between them.

There are important limits. The current plan starts with a single API instance. Scaling horizontally requires deciding which instance owns each stream, how to route commands and how to recover ownership after failures. Dokpod defers that distributed scaling to a future decision. The tests that were run confirmed the adapter works with Podman on Linux; that does not replace validating each combination of versions and environment. The Windows agent still depends on qualification gates. The choice of protocol does not automatically certify every engine or operating system.

How Dokpod’s gRPC flow works

The agent opens AgentControl.Connect and sends AgentHello as the first message. The hello reports the agent version, the engine and its version, the operating system, the architecture, the hostname and the capabilities. The server obtains the client certificate from the TLS connection and hands the certificate and the hello to the session negotiator. If the identity or the negotiation is rejected, the call ends with a gRPC error; there is no valid session just because TCP connected.

When it accepts the session, the control plane returns SessionEstablished: the selected protocol version, the session identifier, the fencing token, the heartbeat interval, the message limit and the accepted capabilities. The agent validates that metadata before starting the session’s work. The advertised interval is 15 seconds and the service uses a heartbeat timeout of 90 seconds. Those numbers describe the code consulted, not a universal recommendation for any network.

After the negotiation, the agent can publish paginated snapshots and inventory deltas. The snapshot rebuilds the complete state in parts; the delta represents changes from a base revision. Heartbeats include the last applied command sequence and inventory revisions. The API can also send reconciliation requests, queries and domain commands. Separating “accepted” from “result completed” makes it possible to represent that receiving the order does not mean the engine has already finished the operation.

gRPC diagram in Dokpod separating REST and SignalR from the mTLS channel between agent and API

The snippet below summarizes the shape of the contract, without trying to reproduce every message:

1
2
3
4
5
// Summarized contract: the real types are defined in the same .proto file.
service AgentControl {
  rpc Connect(stream AgentMessage) returns (stream ControlPlaneMessage);
  rpc Exec(stream ExecFrame) returns (stream ExecFrame);
}

📂 Source Code: The complete contract is on Dokpod’s main branch: agent.proto.

On the client, the agent writes the hello, waits for the initial confirmation and only then considers the session established. The generated code provides the types and the service proxy; the logic below shows the validation point, not a complete client:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// Opens Connect and presents the hello before sending other events.
using var call = connect(stoppingToken);
await call.RequestStream.WriteAsync(hello, stoppingToken);

if (!await call.ResponseStream.MoveNext(stoppingToken) ||
    call.ResponseStream.Current.PayloadCase !=
        ControlPlaneMessage.PayloadOneofCase.SessionEstablished)
{
    throw new RpcException(new Status(
        StatusCode.FailedPrecondition, "agent_session_not_established"));
}

📂 Source Code: The session and reconnection flow is in AgentControlWorker.cs; the server-side processing is in AgentControlService.cs.

The terminal uses AgentControl.Exec, a separate stream that starts with a handshake bound to the certificate identity, the active session, the fencing token and a pending terminal session. It carries input, output, resize and status frames. A separate channel avoids mixing the interactive flow with heartbeats and inventory, but it requires limits, expiration and coordinated shutdown.

Security, reconnection and reliability

gRPC is not a security policy. TLS protects the channel and authenticates the server; mTLS adds a client certificate, which lets the server authenticate the agent’s identity. In Dokpod’s flow, the API requires the client certificate and negotiates the session based on it and on the agent’s information. Certificates need well-defined issuance, rotation, revocation, storage and scope. A valid certificate identifies a participant, but it does not replace business authorization for each command.

It helps to separate four questions: who established the channel? Which environment does that identity belong to? Does the protocol accept the advertised version and capabilities? Can the identity execute this operation, on this resource, at this moment? Answering only the first question with mTLS would leave the rest unanswered. The server needs to validate authorization before persisting or sending commands; the agent must also refuse invalid payloads and operations it does not implement.

Persistent connections drop. The process may restart, the network may change, a NAT may expire the mapping or the server may end a call. The agent tries to reconnect, but the new connection must not simply carry on as if it were the old one. A session receives an identifier and a fencing token: an increasing number that makes it possible to distinguish the current session from an old connection that reappeared late. The server rejects messages that arrive with an obsolete session or token.

Command sequences and identifiers help detect duplicate messages and gaps. However, the gRPC transport does not provide exactly-once delivery. If a response is lost after the operation was applied, the agent may not know whether it should repeat it. Dokpod assumes at-least-once delivery in some flows and combines deduplication, a journal and reconciliation to reduce duplicate effects and recover from divergences. That is not an exactly-once guarantee: the outcome must be designed to deal with repetition and uncertain states.

Message size is also part of security. Large messages can consume memory and delay other activities. Dokpod’s server sets a 1 MiB gRPC limit, and query responses are split with a documented limit of 256 KiB. The application must validate its own limits, bound queues and rates, and cancel operations when they are no longer needed. A stream that stays open is not a license to accumulate messages without control.

Finally, high availability does not come from a duplex RPC. The current design starts with one API instance; distributed stream ownership and durable routing are deferred. The readiness review records pending items for N/N-1 compatibility, load and release observability, plus qualification of the Windows agent. That distinction keeps an architectural example from being confused with production certification.

When to choose gRPC, REST, GraphQL or SignalR

I would start with the shape of the consumer and the flow, not with a list of “advantages”. If the clients are controlled services and the team can distribute contracts and generated code, gRPC can simplify a typed integration. If the clients include browsers, scripts, partners or assorted tools, REST usually reduces friction and makes observation easier with well-known HTTP tools. GraphQL addresses another problem: letting consumers query fields and relationships of a data graph through a query-oriented API. SignalR addresses real-time communication with web clients and high-level abstractions such as hubs and groups in the ASP.NET Core ecosystem.

OptionTypical consumerFlow directionContract and payloadOperational cost
gRPCControlled services and agentsUnary and streaming in both directions.proto, generated code, Protobuf by defaultHTTP/2, coordinated contracts and stream diagnostics
RESTBrowsers, apps and integrationsRequest/response; streaming requires a specific designHTTP resources, OpenAPI and frequently JSONLow friction and broad tooling compatibility
GraphQLClients with variable read needsQuery/response through a schemaGraphQL schema and field selectionControl of query cost, resolvers and caching
SignalRBrowsers and connected clientsReal-time events and messagesHubs, methods and application payloadsPersistent connections, groups and scale/backplane when needed

In Dokpod, the browser consumes REST/OpenAPI for operations and SignalR to receive notifications segmented by environment. The relationship between browser and API is different from the relationship between agent and API. That avoids making the web interface depend on the internal gRPC channel. If a product needs gRPC calls originating in the browser, gRPC-Web or a gateway can be evaluated; each option introduces proxy, compatibility and streaming support requirements that need to be proven.

I also would not choose gRPC just because the binary payload looks smaller or because HTTP/2 has multiplexing. Without a representative benchmark, there is no evidence to claim superior performance. If an operation is one-off, simple and aimed at heterogeneous clients, REST may be the clearer choice. If the problem requires flexible queries over many resources, look into GraphQL. If the browser needs to receive events, evaluate SignalR, SSE or WebSockets. If controlled services need to exchange messages continuously with an explicit contract, gRPC deserves a prototype.

Practical Example

Consider the lifecycle of a Dokpod agent. First, it opens an outbound connection to the API and calls Connect. Next, it sends AgentHello with its operational identity and the capabilities it advertises. The server validates the certificate, maps it to an environment and negotiates the session. If the negotiation is approved, it responds with SessionEstablished, which includes the chosen protocol, the fencing token, the heartbeat interval, the message limit and the accepted capabilities.

From then on, the agent and the API can write to the stream. The agent sends heartbeats and publishes paginated inventory or deltas; the control plane sends commands, queries or reconciliation requests. For an operation, the command message carries session and sequence metadata. The agent validates the active session, deduplicates the operation when applicable and returns separate states for acceptance and result. If the connection drops before the result arrives, the API must not assume the command failed nor repeat it blindly: it needs to check the persisted state and reconcile with the agent after reconnecting.

This excerpt of the contract shows how the payload changes without creating a call for each type of event:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// An envelope carries exactly one agent payload at a time.
message AgentMessage {
  MessageMetadata metadata = 1;
  oneof payload {
    AgentHello hello = 10;
    Heartbeat heartbeat = 11;
    InventorySnapshotPage snapshot_page = 12;
    InventoryDelta inventory_delta = 13;
    CommandAccepted command_accepted = 14;
    CommandResult command_result = 15;
  }
}

📂 Source Code: The complete definition, including payloads and field numbering, is in the agent.proto contract.

The teaching value of the example lies in the boundaries between the parts. The protocol defines the shape of the messages; the client keeps the connection and coordinates queues; the API service negotiates and processes events; the adapters talk to Docker or Podman. The API does not forward an arbitrary call to the engine socket. That separation makes it more explicit who can request an operation and which agent capability is required.

The terminal flow is different. The API opens a separate Exec after validating that the agent identity, the session and the fencing token match a pending terminal session. Frames carry input, output, resize and status data. It is not a generic shell provided by gRPC: it is a domain feature with its own authorization, expiration and support conditions. The repository documents that certain terminal actions are limited to Linux agents and advertised capabilities.

To adapt the pattern to another system, start with a minimal hello message, explicit negotiation and a small set of event types. Define how an operation will be identified, how duplicate messages will be handled and how the client discovers the current state after an interruption. Only add bidirectional streaming if both sides really need to produce messages during the same session.

Tips and Good Practices

  • Set deadlines and cancellation. Unary calls should have a deadline appropriate to the work; long operations should observe the cancellation token. Continuous streams need a clear policy for shutdown and reconnection.
  • Never reuse Protobuf numbers. When removing a field, reserve its number and consider reserving the name too. Changes to the .proto should go through a compatibility review and cross-version tests.
  • Limit messages, queues and frequency. Define the maximum size, apply pagination or chunking and use bounded queues. Without limits, a slow client can turn a persistent stream into unbounded memory growth.
  • Authenticate and authorize separately. TLS protects the transport; mTLS identifies the agent’s certificate. You still need to bind the identity to a scope and authorize each command and resource.
  • Design repetition as normal behavior. Use idempotent IDs, deduplication and reconciliation. Do not promise exactly-once because an RPC returned success or because a channel stayed open.
  • Test versions and interruptions. Exercise a drop during sending, a lost response, a server restart, a revoked certificate and an old agent. Theoretical wire format compatibility does not replace N/N-1 testing.
  • Measure before talking about performance. Compare a representative load, the same data and the same topology. Record latency, CPU, memory, bytes, connections and error rate for gRPC and the alternatives.

Conclusion

gRPC combines RPC, contracts defined in .proto, generated code, Protobuf messages and a transport usually based on HTTP/2. Its model supports unary calls, server streaming, client streaming and bidirectional streaming. That set is especially useful when controlled services need to exchange typed messages continuously, but it also requires decisions about contract evolution, resource limits, authentication, authorization, cancellation and recovery.

The Dokpod case shows a choice consistent with the problem: agents on private hosts initiate outbound connections, authenticate with mTLS and keep a channel for control and inventory. The API does not need to expose Docker sockets or SSH, and the protocol carries domain commands, not arbitrary calls to the engine. The web interface uses REST/OpenAPI and SignalR, because the browser and the agent are different consumers with different needs.

That choice does not prove that gRPC is always faster, simpler or better than REST. Nor does it mean the architecture is already qualified for every combination of engine and operating system: although the tests that were run confirm it works with Podman on Linux, there are still gates for load, N/N-1 compatibility, Windows agent qualification and release observability. The correct conclusion is more modest and more useful: use gRPC when a typed contract and a continuous flow justify the operational cost, validate the real network conditions and keep suitable alternatives for other clients.

In part 2 of the APIs and Communication in .NET series, I will cover GraphQL for beginners and the problems a query-oriented API solves. In part 3, I will focus on SignalR in .NET, including hubs, clients, reconnection and operations. Until then, the published article on real time in Angular and .NET remains complementary reading on WebSockets, SSE, SignalR and Long Polling, but it is not part of this new series.

Objective Summary

  • gRPC — an RPC framework that describes services and messages in contracts, generates client/server code and usually carries calls over HTTP/2.
  • Protocol Buffers — the language and binary format associated with gRPC; each field has a stable number that must not be reused after publication.
  • Bidirectional streaming — lets client and server send several messages during the same call, without requiring them to alternate on each send.
  • Dokpod — uses gRPC with mTLS on the internal channel between the API and the agents; the browser uses REST/OpenAPI and SignalR.
  • Reliability — gRPC does not offer exactly-once delivery or high availability by itself; repetition, deduplication, fencing and reconciliation belong to the application design.
  • Adoption — gRPC fits when typed contracts and continuous flows justify operating it; REST, GraphQL and SignalR serve different client and traffic needs.

Read Also

References