anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-23 02:36:57 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

[PR #6487] feat: add gRPC transport alongside HTTP server #11929

New Issue
Closed
opened 2026-02-16 18:16:52 -05:00 by yindo · 0 comments
yindo commented 2026-02-16 18:16:52 -05:00
Owner
Copy Link
Copy Source

Original Pull Request: https://github.com/anomalyco/opencode/pull/6487

State: closed
Merged: No

This PR introduces an opt-in gRPC transport to the OpenCode server, running alongside the existing HTTP interface. It provides a strongly-typed, backpressure-aware API surface suitable for headless clients, remote tooling, and multi-client workflows.

Scope

The gRPC transport is additive and optional. No existing HTTP behavior or APIs are changed.

What’s included

  • New gRPC server transport

    • Enabled via opencode serve --grpc [--grpc-port <N>]
    • Runs concurrently with the HTTP server
    • Uses shared service logic to preserve parity

  • Services exposed (opencode.v1)

    • ProjectService – list/get projects
    • SessionService – create/get/list sessions
    • EventService – server-streaming event subscription with cursor resumption
    • PtyService – bidirectional PTY streaming with strict lifecycle enforcement
    • HealthService – standard gRPC health checks

  • Authentication parity

    • Mirrors HTTP auth via OPENCODE_TOKEN
    • Bearer token passed through gRPC metadata
    • UNAUTHENTICATED / PERMISSION_DENIED mapped consistently

  • Workspace scoping

    • Per-RPC workspace selection via x-opencode-directory metadata
    • Defaults to process CWD when omitted

  • Event persistence & resumption

    • Disk-backed event log (events.jsonl)
    • Configurable retention (count / bytes)
    • Cursor-based resume with explicit reset contract when pruned
    • EventService.Info exposes cursor bounds and retention limits

  • PTY protocol guarantees

    • Explicit state machine (IDLE → OPEN → ACTIVE → CLOSED)
    • Strict validation of invalid transitions
    • Ordered output delivery before exit
    • Backpressure enforcement with deterministic termination

  • Operational hardening

    • Message size limits
    • Structured metrics in logs
    • Optional gRPC reflection (env-gated)
    • Health checks for readiness

  • Tests & verification

    • gRPC integration tests
    • HTTP ↔ gRPC conformance tests for shared functionality
    • PTY protocol violation tests
    • Typechecking verified

Non-goals

  • No removal or deprecation of HTTP APIs
  • No UI changes
  • No breaking protocol changes (all protos are additive under opencode.v1)

Why this belongs in core (not a plugin)

This defines a stable transport boundary, not an internal feature:

  • Required for headless and multi-client usage
  • Enforces backpressure, ordering, and lifecycle semantics
  • Participates in core auth, workspace scoping, and persistence
  • Versioned and testable as part of the public API surface

Docs

  • Added GRPC_TRANSPORT.md as the implementation and usage reference
  • Includes configuration, limits, protocol semantics, and client guidance

Follow-ups

  • Monitor production metrics post-release
  • Collect client feedback during v1 stabilization window
  • Defer any breaking changes to a future opencode.v2
**Original Pull Request:** https://github.com/anomalyco/opencode/pull/6487 **State:** closed **Merged:** No --- This PR introduces an **opt-in gRPC transport** to the OpenCode server, running alongside the existing HTTP interface. It provides a strongly-typed, backpressure-aware API surface suitable for headless clients, remote tooling, and multi-client workflows. ### Scope The gRPC transport is **additive and optional**. No existing HTTP behavior or APIs are changed. ### What’s included - **New gRPC server transport** - Enabled via `opencode serve --grpc [--grpc-port <N>]` - Runs concurrently with the HTTP server - Uses shared service logic to preserve parity - **Services exposed (`opencode.v1`)** - `ProjectService` – list/get projects - `SessionService` – create/get/list sessions - `EventService` – server-streaming event subscription with cursor resumption - `PtyService` – bidirectional PTY streaming with strict lifecycle enforcement - `HealthService` – standard gRPC health checks - **Authentication parity** - Mirrors HTTP auth via `OPENCODE_TOKEN` - Bearer token passed through gRPC metadata - `UNAUTHENTICATED` / `PERMISSION_DENIED` mapped consistently - **Workspace scoping** - Per-RPC workspace selection via `x-opencode-directory` metadata - Defaults to process CWD when omitted - **Event persistence & resumption** - Disk-backed event log (`events.jsonl`) - Configurable retention (count / bytes) - Cursor-based resume with explicit reset contract when pruned - `EventService.Info` exposes cursor bounds and retention limits - **PTY protocol guarantees** - Explicit state machine (`IDLE → OPEN → ACTIVE → CLOSED`) - Strict validation of invalid transitions - Ordered output delivery before exit - Backpressure enforcement with deterministic termination - **Operational hardening** - Message size limits - Structured metrics in logs - Optional gRPC reflection (env-gated) - Health checks for readiness - **Tests & verification** - gRPC integration tests - HTTP ↔ gRPC conformance tests for shared functionality - PTY protocol violation tests - Typechecking verified ### Non-goals - No removal or deprecation of HTTP APIs - No UI changes - No breaking protocol changes (all protos are additive under `opencode.v1`) ### Why this belongs in core (not a plugin) This defines a **stable transport boundary**, not an internal feature: - Required for headless and multi-client usage - Enforces backpressure, ordering, and lifecycle semantics - Participates in core auth, workspace scoping, and persistence - Versioned and testable as part of the public API surface ### Docs - Added `GRPC_TRANSPORT.md` as the implementation and usage reference - Includes configuration, limits, protocol semantics, and client guidance ### Follow-ups - Monitor production metrics post-release - Collect client feedback during v1 stabilization window - Defer any breaking changes to a future `opencode.v2`
yindo added the pull-request label 2026-02-16 18:16:52 -05:00
yindo closed this issue 2026-02-16 18:16:52 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#11929
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?