Skip to content

proposal: added golang bindings for CPEX core#40

Closed
terylt wants to merge 1 commit into
mainfrom
docs/golang_proposal
Closed

proposal: added golang bindings for CPEX core#40
terylt wants to merge 1 commit into
mainfrom
docs/golang_proposal

Conversation

@terylt
Copy link
Copy Markdown
Contributor

@terylt terylt commented Apr 24, 2026

Summary

Adds the CPEX Go Bindings Proposal — a design document for embedding the CPEX Rust plugin runtime in Go applications
via C FFI and MessagePack serialization.

Changes

What the proposal covers

  • Architecture: Rust plugins with a Go host. Plugins written in Rust for security guarantees and native execution.
    Go manages lifecycle and invocation. Single FFI crossing per invoke — no per-plugin serialization round-trips.
  • MessagePack boundary: Payloads and extensions serialize via MessagePack. ContextTable and BackgroundTasks are
    opaque Rust handles passed by pointer — never serialized.
  • Go SDK: PluginManager wrapper with NewPluginManager, Initialize, Shutdown, InvokeByName, typed
    Invoke[P], HasHooksFor, PluginCount. Clean Go API hiding all C FFI internals.
  • Security guarantees: Immutable payloads, monotonic sets (add-only labels), append-only delegation chains,
    guarded fields (write tokens), capability gating enforced by Rust's type system.
  • Full extension model: MetaExtension (routing), SecurityExtension (Subject, AgentIdentity, claims),
    DelegationExtension (scope-narrowing chain), HttpExtension (headers, method, path), Labels (monotonic set),
    FilteredExtensions (capability-gated view).
  • CMF types: Go mirror of the Python CMF Message model — Role, Channel, ContentPart (text, image, tool_call,
    tool_result, resource, prompt, etc.), ToolCall, ToolResult, Resource, Metadata.
  • Complete example: Go host loading YAML config, invoking CMF pre/post hooks with routing, threading ContextTable
    across hooks, awaiting BackgroundTasks.
  • Planned features: Reverse-order response hooks, required plugins, bypass/passthrough, adapter helpers, body
    buffering budget.
  • Future extensions: Go-native plugins (Option C) with optimized FFI for the no-modification fast path. WASM
    plugins with sandbox tradeoffs.
  • C FFI surface: Minimal API with opaque handles for manager, context table, and background tasks.

Test plan

  • Design review with team
  • Validate Go SDK types against Rust core types
  • Prototype C FFI for cpex_invoke round-trip
  • Benchmark MessagePack encode/decode overhead for typical CMF payloads

Signed-off-by: Teryl Taylor <terylt@ibm.com>
@araujof araujof changed the title Proposal: added golang bindings for CPEX core. Proposal: added golang bindings for CPEX core May 1, 2026
@araujof araujof added this to CPEX May 1, 2026
@araujof araujof added this to the 0.2.0 milestone May 1, 2026
@github-project-automation github-project-automation Bot moved this to Backlog in CPEX May 1, 2026
@araujof araujof changed the title Proposal: added golang bindings for CPEX core proposal: added golang bindings for CPEX core May 1, 2026
@araujof
Copy link
Copy Markdown
Contributor

araujof commented May 8, 2026

Superseded by #45

@araujof araujof closed this May 8, 2026
@github-project-automation github-project-automation Bot moved this from Backlog to Done in CPEX May 8, 2026
@araujof araujof deleted the docs/golang_proposal branch May 8, 2026 14:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants