Introduce v2 runtime and generator#42
Open
noxiouz wants to merge 3 commits into
Open
Conversation
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
reviewed
Jun 5, 2026
cgwalters
left a comment
There was a problem hiding this comment.
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.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.