Skip to content

Introduce v2 runtime and generator#42

Open
noxiouz wants to merge 3 commits into
varlink:masterfrom
noxiouz:v2
Open

Introduce v2 runtime and generator#42
noxiouz wants to merge 3 commits into
varlink:masterfrom
noxiouz:v2

Conversation

@noxiouz

@noxiouz noxiouz commented Apr 23, 2026

Copy link
Copy Markdown
Collaborator

Add a separate github.com/varlink/go/v2 module that can evolve independently from the v1 API while preserving the root module. The v2 design splits the implementation into explicit codec, wire, runtime, and generated API layers so framing, JSON handling, request semantics, and typed bindings can be optimized and reasoned about separately.

The internal codec now owns null-delimited framing, bounded frame reads, caller-owned buffer reuse, net.Buffers-based writes, and a JSON wire layer. It also supports both the default encoding/json backend and the experimental encoding/json/v2 backend behind GOEXPERIMENT=jsonv2. Frame and wire tests plus benchmarks cover small, medium, and large messages, fragmented reads, oversized frames, EOF behavior, and write-path allocation shape.

The v2 runtime adds explicit client and server APIs for unary calls, oneway requests, streamed replies, upgrades, and pipelined unary/oneway batches. Server registration is builder-based and immutable after Build, with separate handler types for unary, stream, and upgrade methods. The runtime includes built-in org.varlink.service support, service metadata, interface descriptions, typed remote errors, deadline-aware framed transport helpers, and certification-style coverage for the core varlink data shapes.

Add a lightweight v2 introspection package that extracts interface metadata and method modes from interface descriptions. Method mode is expressed through structured comments such as @mode stream, @mode oneway, and @mode upgrade, with unannotated methods defaulting to unary because plain varlink IDL does not encode transport mode. The certification IDL is annotated accordingly for streamed and oneway methods.

Add a v2 interface generator that reuses the existing IDL parser but emits github.com/varlink/go/v2/varlink bindings. Generated code now includes typed request/reply/error declarations, typed clients, typed batch helpers for unary and oneway calls, typed stream receivers, typed upgrade methods, mode-correct server handler adapters, interface descriptions, and remote-error dispatch. The legacy generator and parser also learn the official any type.

This commit intentionally keeps v1 code intact while creating a compileable v2 staging area. Remaining work is mostly around higher-level transport helpers, resolver integration, richer public schema APIs, external cross-language certification, and broader examples/CI coverage.

Add a separate github.com/varlink/go/v2 module that can evolve independently
from the v1 API while preserving the root module. The v2 design splits the
implementation into explicit codec, wire, runtime, and generated API layers so
framing, JSON handling, request semantics, and typed bindings can be optimized
and reasoned about separately.

The internal codec now owns null-delimited framing, bounded frame reads,
caller-owned buffer reuse, net.Buffers-based writes, and a JSON wire layer. It
also supports both the default encoding/json backend and the experimental
encoding/json/v2 backend behind GOEXPERIMENT=jsonv2. Frame and wire tests plus
benchmarks cover small, medium, and large messages, fragmented reads, oversized
frames, EOF behavior, and write-path allocation shape.

The v2 runtime adds explicit client and server APIs for unary calls, oneway
requests, streamed replies, upgrades, and pipelined unary/oneway batches. Server
registration is builder-based and immutable after Build, with separate handler
types for unary, stream, and upgrade methods. The runtime includes built-in
org.varlink.service support, service metadata, interface descriptions, typed
remote errors, deadline-aware framed transport helpers, and certification-style
coverage for the core varlink data shapes.

Add a lightweight v2 introspection package that extracts interface metadata and
method modes from interface descriptions. Method mode is expressed through
structured comments such as @mode stream, @mode oneway, and @mode upgrade, with
unannotated methods defaulting to unary because plain varlink IDL does not encode
transport mode. The certification IDL is annotated accordingly for streamed and
oneway methods.

Add a v2 interface generator that reuses the existing IDL parser but emits
github.com/varlink/go/v2/varlink bindings. Generated code now includes typed
request/reply/error declarations, typed clients, typed batch helpers for unary
and oneway calls, typed stream receivers, typed upgrade methods, mode-correct
server handler adapters, interface descriptions, and remote-error dispatch. The
legacy generator and parser also learn the official any type.

This commit intentionally keeps v1 code intact while creating a compileable v2
staging area. Remaining work is mostly around higher-level transport helpers,
resolver integration, richer public schema APIs, external cross-language
certification, and broader examples/CI coverage.

Co-authored-by: Codex GPT-5 <codex@openai.com>

@cgwalters cgwalters left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since I'm trying to contribute to this repo (ref #44 ) I thought I'd spend some tokens reviewing this PR.

Assisted-by: OpenCode (Claude Opus 4.8 + Gemini 3.1 Pro)

AI-generated review. Comments prefixed with AI: are unedited AI output. Verified locally: the v2 module builds, go vet, go test, go test -race, and GOEXPERIMENT=jsonv2 go test ./internal/codec/... all pass.

Comment thread v2/varlink/server_runtime.go Outdated
Comment thread v2/varlink/client_runtime.go
Comment thread v2/internal/codec/json_backend_v2.go Outdated
Comment thread v2/varlink/runtime.go Outdated
Comment thread v2/varlink/server_runtime.go Outdated
Comment thread v2/internal/codec/json_backend_std.go Outdated
Comment thread v2/varlink/server_runtime.go Outdated
Comment thread v2/varlink/introspect/introspect.go Outdated
Comment thread v2/varlink/errors.go
Comment thread v2/internal/codec/frame.go Outdated
noxiouz added 2 commits June 12, 2026 00:07
Fix the v2 runtime and codec issues raised during review so upgrades, stream errors, cancellation, panic recovery, and JSON backend behavior are safer.

Use detached transports for server upgrades, make ordered client I/O failures close the client, recover handler panics with a declared service error, copy raw JSON values, align jsonv2 with v1 options, and add focused regression tests.
Keep the PR 42 follow-up changes focused on correctness without expanding the public service introspection surface or closing clients on local decode errors.

Return upgraded state only after upgrade acceptance, recover handler panics by closing the serving connection without an undeclared remote error, preserve unary client reuse after local decode failures, and add regression coverage.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants