gRPC Communication Layer
Relevant source files
The following files were used as context for generating this wiki page:
The coral-grpc crate implements the private native gRPC adapter for the Coral project. It provides the communication interface between the Coral runtime and external clients, specifically the Reef management interface. The layer owns wire contracts, request metadata, and safe status projection while delegating domain logic to underlying modules.
Sources: crates/coral-grpc/src/lib.rs:1-12, apps/reef/README.md:52-56
Architecture and Components
The gRPC layer functions as a thin presentation and transport adapter. It composes application-constructed domain modules and exposes them through a set of defined gRPC services.
Core Dependencies
The routes function accepts a Dependencies struct containing references to various system modules:
- Organization and Workspaces: Manages membership and workspace lifecycle.
- Providers and Accounts: Handles service integrations and credential management.
- Runs and Tasks: Manages program execution and asynchronous agent work.
- Saved Functions: Handles the inspection and deletion of user-defined functions.
- Policies: Enforces operation-level access controls.
Sources: crates/coral-grpc/src/grpc.rs:25-42, crates/coral-grpc/tests/grpc.rs:175-207
Component Diagram
The following diagram illustrates the relationship between the gRPC adapter, the transport context, and the domain modules.
Management Services
The gRPC layer defines several Protobuf-based services for administrative and operational tasks.
Workspace Service
Manages the lifecycle and configuration of human Workspaces. It allows users to create, list, and archive workspaces.
| RPC Method | Request Type | Response Type | Description |
|---|---|---|---|
CreateWorkspace | CreateWorkspaceRequest | Workspace | Creates an active Workspace and assigns Owner role to the creator. |
ListWorkspaces | ListWorkspacesRequest | ListWorkspacesResponse | Lists workspaces where the user holds membership. |
GetWorkspace | GetWorkspaceRequest | Workspace | Inspects workspace details without granting access to private data. |
ArchiveWorkspace | ArchiveWorkspaceRequest | Workspace | Stops configuration and dispatching. |
Sources: crates/coral-grpc/proto/coral/management/v1/workspace.proto:6-18
Saved Function Service
Provides inspection and deletion for a user's own Saved Functions within a workspace.
| RPC Method | Request Type | Response Type | Description |
|---|---|---|---|
ListSavedFunctions | ListSavedFunctionsRequest | ListSavedFunctionsResponse | Returns source-free summaries in path order. |
GetSavedFunction | GetSavedFunctionRequest | SavedFunction | Returns function source, declaration, and diagnostics. |
DeleteSavedFunction | DeleteSavedFunctionRequest | Empty | Deletes the function and records a lifecycle event. |
Sources: crates/coral-grpc/proto/coral/management/v1/saved_function.proto:11-18
Authentication and Security
The gRPC layer enforces security through PrincipalAuthentication and metadata-based checks.
- Audience Validation: Requests must specify a
coral-audience(e.g., "reef" or "mcp") in the metadata. - Bearer Tokens: Authenticated Reef uses native gRPC over HTTP/2 and attaches server-held bearer tokens.
- Membership Requirements: Access to workspace resources requires an active membership, even for Organization Owners.
- Token Scope: Tokens issued for one audience (like "mcp") are rejected when used for management audiences (like "reef").
Sources: crates/coral-grpc/tests/grpc.rs:248-261, crates/coral-grpc/tests/grpc.rs:331-335, apps/reef/README.md:52-56
Authentication Flow
The following sequence diagram shows the authentication and authorization check for a gRPC request.
System Health and Readiness
The gRPC layer includes a ReadinessProbe to report the system's operational status.
- Health Service: Uses
tonic_healthto implement the standard gRPC Health Checking Protocol. - Readiness State: A workspace-aware probe determines if the server is ready to accept traffic.
- Status Mapping: Database outages or authentication unavailability are reported as
tonic::Code::Unavailable.
Sources: crates/coral-grpc/src/health.rs:8-18, crates/coral-grpc/tests/grpc.rs:504-508
Protocol Buffers and Wire Namespaces
The project organizes its Protobuf definitions into distinct namespaces under coral:
| Namespace | Path | Purpose |
|---|---|---|
coral.internal.v1 | crates/coral-grpc/proto/coral/internal/v1 | Internal MCP support contracts for agent work. |
coral.management.v1 | crates/coral-grpc/proto/coral/management/v1 | Reef management contracts for human administration. |
Sources: crates/coral-grpc/src/lib.rs:24-49, crates/coral-grpc/tests/grpc.rs:608-615
Conclusion
The gRPC Communication Layer serves as the primary backbone for administrative interactions in Coral. By separating wire-level concerns (health, metadata, status codes) from domain logic, it ensures that the management interface remains secure, performant, and type-safe across the Coral ecosystem.