Skip to content

codegen: add opt-in native adapter generation - #835

Open
vanderbr wants to merge 2 commits into
anthropics:mainfrom
reallyme:feature/native-adapters
Open

vanderbr wants to merge 2 commits into
anthropics:mainfrom
reallyme:feature/native-adapters

Conversation

@vanderbr

@vanderbr vanderbr commented Nov 18, 2026 •

Copy link
Copy Markdown

Motivation

Downstream libraries sometimes need a process-local Rust API alongside their portable protobuf model: selectors that reject unspecified and unknown values, selectors with validated value payloads, and borrowed inputs with callback or provider references. COSE currently maintains parallel enum-generation scripts to preserve those signatures, which makes schema changes easy to miss.

This adds a generic, opt-in adapter generator so the descriptor and explicit metadata define those native declarations together.

Changes

  • Add typed (buffa.ext.file).adapters options, the Rust AdapterConfig API, and a strict JSON representation capped at 1 MiB.
  • Expose schema selection through buffa_build::Config::generate_adapters(true) and adapters=true; explicit Rust configurations and adapter_manifest=<path> also work independently.
  • Generate closed selectors with complete case coverage, explicit legacy normalization, optional external registrations, checked conversions, and canonical reverse conversions. Zero and unknown values are rejected, including an explicitly constructed EnumValue::Unknown carrying a recognized number. Legal numeric aliases are supported.
  • Generate Copy payload selectors and lifetime-bearing borrowed adapters, including byte slices and declared capability traits. Borrowed declarations have no generated codec, cloning, Debug or cleanup implementation.
  • Emit standalone GeneratedFileKind::Adapter files. Applications include them in their native API modules and retain control of module feature gates. Portable package trees exclude adapter files, and normalized output collisions and reserved Windows device filenames are rejected before writes on every host.
  • Add fixed typed adapter diagnostics, malformed-metadata regressions, a guide, and the required changelog fragment.

Descriptor shape, source coverage, path syntax and Copy bounds are checked mechanically. Application-supplied Rust type bindings, opaque value invariants, domain validation, cryptographic implementations and policy remain application responsibilities; the guide states this boundary explicitly.

Compatibility and validation

Adapter generation defaults to off. Tests compare portable output with the feature off and on, and preserve wire/JSON names. The COSE fixture covers 17 closed selectors, two payload selectors and five borrowed adapters, including legacy inputs, external identifiers, caller-buffer identity, callbacks, and lifetime/Debug compile-fail checks. The generator contains no COSE-specific algorithm or policy tables.

Validated against upstream main without other feature branches:

  • Workspace tests with default features and with all features.
  • Strict Clippy with all targets, for default and all-feature configurations; formatting, strict rustdoc, Markdown and workflow checks.
  • Generated downstream consumer tests and strict Clippy without std, wasm32-unknown-unknown compilation, and an edition-2024 consumer build. Regressions include legal primitive-name shadowing and raw keyword module paths.
  • Rust 1.75 workspace and focused adapter/plugin checks, with generated-consumer runtime compatibility also verified. The edition-2024 consumer check runs on compilers that support that edition.
  • Bootstrap, WKT and option bindings regenerated and checked for drift; package publication order checked.
  • Output portability follow-up: all 18 adapter tests and strict pinned all-feature Clippy pass; downstream library compilation is verified on Rust 1.75.
  • Focused line coverage of the new adapter modules: 94.5% (959/1,015 lines).

Upstream package versions, MSRV 1.75 and the pinned development toolchain remain unchanged. The generator adds a dependency on buffa-proto-options and reuses workspace Serde dependencies for metadata. At release preparation, the codegen dependency floor must advance to the release containing the new option types so published consumers receive matching bindings.

The larger diff is primarily the checked-in generated option bindings and compatibility fixtures. The implementation and guide are in buffa-codegen/src/adapters/ and docs/native-adapters.md.

Generate descriptor-checked closed selectors, payload selectors and borrowed adapters through explicit build, plugin or schema configuration. Keep native declarations separate from portable output and retain caller ownership of borrowed buffers and capabilities.

Validate complete mappings, legacy normalization, external registrations, restricted type paths and output destinations. Include fixed typed diagnostics, typed option bindings, documentation and native/no_std/WASM compatibility tests without changing upstream versions or compiler policy.
@github-actions

Copy link
Copy Markdown

All contributors have signed the CLA ✍️ ✅
Posted by the CLA Assistant Lite bot.

Keep output filenames portable by rejecting case-insensitive Windows device
stems even when followed by .rs. Use the existing fixed InvalidOutput reason
for selector, payload and borrowed adapters without changing valid output.

Test all documented numbered device stems, mixed case and nearby valid names.
All 18 adapter tests and strict pinned Clippy pass. The library also compiles
as a downstream dependency with Rust 1.75; preserve upstream versions and lock.

This branch has not been deployed

No deployments
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.

1 participant