SebastienMelki/sebuf

This system is a collection of Protocol Buffer code generation plugins that automatically produce HTTP server handlers and typed client libraries for Go, TypeScript, and Python. It enables developers to define API contracts in .proto files and generate fully functional, strongly-typed code for both server-side implementations and client-side consumption. The toolset supports advanced features such as custom JSON encoding strategies, Server-Sent Events streaming, and structured error handling, while also generating OpenAPI v3 specifications for documentation.

13 changes.

The project was initialized with essential build infrastructure, dependency management, and CI configuration. Core functionality was established through the development of protoc plugins for HTTP code generation and OpenAPI v3 specification creation, including support for custom JSON encoding and structured error handling.

28 changes.

This period focused on expanding the framework's code generation capabilities to support TypeScript and Python clients and servers alongside the existing Go ecosystem. It introduced new protoc plugins for TypeScript and Python, featuring configurable runtimes and error handling strategies, while simultaneously enriching the Go generator with advanced HTTP binding and serialization fixes. The work was heavily supported by a comprehensive suite of new examples and test fixtures demonstrating these multi-language and multi-service capabilities.

The \http\ package now implements the Go \error\ interface for \ValidationError\ and \Error\ types, allowing them to be used with standard Go error handling functions like \errors.As\ and \errors.Is\. \ValidationError\ provides a formatted string representation of field violations, while \Error\ returns its internal message. This change enables better integration with Go's native error handling patterns for structured validation and handler errors.

http · high confidence

A new example project has been added at examples/rn-client-demo that demonstrates a full-stack Protobuf workflow using React Native. It includes a Go-based HTTP server with in-memory task storage, a TypeScript client generated via protoc plugins, and an Expo-based mobile app that exercises CRUD operations, pagination, and validation against the server.

examples/rn-client-demo · high confidence

A new protoc plugin (cmd/protoc-gen-ts-server) has been introduced to generate TypeScript server-side code from Protobuf definitions. The generator supports two distinct message runtime modes: 'protobuf-es' and 'hand-rolled', which can be selected via the 'ts\_runtime' parameter. This allows users to choose the underlying serialization library that best fits their project's dependencies.

cmd/protoc-gen-ts-server · high confidence

Added a new example in examples/error-handler that demonstrates the WithErrorHandler ServerOption feature of sebuf. The example includes a Go server implementation (main.go) and proto definitions (models/errors.proto, models/user.proto, services/user\_service.proto) showing five distinct error handling strategies: logging errors, adding custom headers, setting custom HTTP status codes, returning custom protobuf error bodies, and writing directly to the response. It also provides a Makefile for running the demo and testing API endpoints, along with buf configuration files for code generation.

examples/error-handler · high confidence

This change introduces a new example in \examples/market-data-unwrap\ that demonstrates how to use the \(sebuf.http.unwrap)\ annotation to serialize map values as direct arrays in JSON, avoiding the nested object structure typically produced by Protobuf maps. The example includes generated Go code for a \MarketDataService\ with endpoints like \GET /v2/options/bars\, a Makefile for building and running the demo, and a client example showing how to consume the unwrapped response format.

examples/market-data-unwrap · high confidence

A new example located at examples/nested-resources has been added to showcase complex nested resource hierarchies with up to three path parameters (e.g., /orgs/{org\_id}/teams/{team\_id}/members/{member\_id}). This self-contained demo includes the Go implementation, Protobuf definitions for Organizations, Teams, Members, and Projects, and a Makefile to generate code and run the server. It demonstrates how the framework handles deep nesting, query parameter filtering, and request body binding in a GitHub-like organizational structure.

examples/nested-resources · high confidence

A new internal code generator (protoc-gen-py-client) produces Python HTTP client libraries from protobuf service definitions. The generated code is standard-library-only (urllib) but supports plugging in any duck-typed HTTP transport (e.g., httpx, requests, aiohttp) via client options. It emits dataclasses for messages, IntEnums for enums, and a client class per service with typed options and per-call options. The generator handles JSON encoding/decoding for scalars, well-known types (Timestamp, Duration, Any, etc.), bytes (base64/hex), and enums (string/number), and supports annotations for int64 encoding, timestamp format, bytes encoding, nullable fields, unwrap, flatten, and oneof discriminators. Error handling includes a hierarchy (ApiError, ValidationError, per-\*Error-message classes) and a registry to map non-2xx responses to specific exceptions. SSE streaming methods are detected and raise NotImplementedError with a tracking link. The generator validates URL parameters at generation time and ensures deterministic output for stable golden tests.

internal/pyclientgen · high confidence

Introduces a complete, runnable example demonstrating user management and authentication APIs generated from Protobuf definitions. The example includes a Makefile with a 'demo' target that installs tools, generates code, and runs the server, along with a .gitignore to exclude generated artifacts. It showcases features like automatic request validation via buf.validate annotations, header validation, mock server generation, and OpenAPI documentation, providing a concrete reference for building HTTP APIs with sebuf.

examples/simple-api · high confidence

New Dockerfiles have been added to the docker directory to provide containerized builds for the protoc-gen-go-http and protoc-gen-openapiv3 plugins. These files define multi-stage builds using Go 1.21 Alpine images, resulting in minimal final images that include the respective compiled binaries and necessary tools like protoc, enabling users to run these code generation tools in isolated environments.

docker · high confidence

The new \internal/tsservergen\ package introduces the \protoc-gen-ts-server\ plugin, which generates TypeScript server-side code for protobuf services. It supports two message runtimes: a hand-rolled implementation and the \@bufbuild/protobuf\ (protobuf-es) runtime. The generator emits per-proto type modules, a shared errors module, and slimmed server modules per service, along with per-package barrel files. It includes validation to reject unsupported path/query parameters (like enums in es-mode) and annotated messages that conflict with es-mode serialization. The location also adds extensive test coverage, including golden file comparisons, cross-generator type consistency checks against the client generator, TypeScript type-checking, and wire-conformance proofs.

internal/tsservergen · high confidence

The repository has been initialized with essential configuration files to support development and release workflows. This includes a Makefile for build and test automation, a .goreleaser.yml configuration for packaging the \protoc-gen-go-http\ and \protoc-gen-openapiv3\ binaries, and an .editorconfig to enforce consistent coding styles across Go, TypeScript, and Protocol Buffer files. Additionally, configuration for local CI testing via \nektos/act\ (.actrc) and environment variable examples (.env.act.example) have been added to streamline local development.

(repo-wide) · high confidence

The \cmd/protoc-gen-openapiv3\ tool now generates OpenAPI v3 specifications instead of the previous version. By default, it creates one OpenAPI file per gRPC service for better organization, but also supports an origin-level bundle mode (enabled via \bundle=true\) to combine all services into a single document with configurable metadata (title, version, servers, etc.). The generator validates inputs by rejecting non-scalar query and path parameters to ensure valid URL contracts, and supports both JSON and YAML output formats.

cmd/protoc-gen-openapiv3 · high confidence

A new protoc-gen-go-client plugin has been added to generate Go HTTP clients from Protobuf definitions. The entry point registers support for the proto3 optional feature and delegates code generation to the internal clientgen package.

cmd/protoc-gen-go-client · high confidence

A new command-line tool located at cmd/protoc-gen-go-http has been added to the codebase. This tool acts as the entry point for the HTTP code generator, allowing users to invoke the generation process via the protoc plugin interface. It supports a specific command-line flag, --generate\_mock, which enables the generation of mock server implementations alongside standard HTTP handlers.

cmd/protoc-gen-go-http · high confidence

The \internal/clientgen\ package now provides a dedicated \protoc-gen-go-client\ plugin for generating Go HTTP clients. This generator introduces strict validation to reject invalid path/query parameters and conflicting enum annotations (e.g., \enum\_encoding=NUMBER\ combined with \enum\_value\). It supports advanced encoding features including int64, enum, nullable, bytes, and flatten transformations, as well as SSE streaming and \discardUnknownFields\ options. The generated clients use a custom \sebufUnmarshaler\ interface to ensure consistent JSON unmarshaling behavior across different encoding modes.

internal/clientgen · high confidence

The \proto/sebuf\ area introduces a new set of Protocol Buffer definitions to configure HTTP/JSON behavior for gRPC services. \annotations.proto\ adds method and service-level options for defining HTTP paths, verbs (GET, POST, etc.), and Server-Sent Events (SSE) streaming, alongside granular controls for JSON serialization such as int64/enum encoding, timestamp formats, bytes encoding, oneof flattening, and query parameter mapping. \errors.proto\ defines structured \ValidationError\ and \Error\ messages to standardize API error responses, while \headers.proto\ provides service and method-level configurations for required HTTP headers, supporting OpenAPI specification generation.

proto/sebuf · high confidence

The examples/restful-crud directory now provides a complete, runnable example of a RESTful CRUD API for products, including the server implementation (main.go), Protobuf definitions (product.proto, product\_service.proto), and code generation configuration (buf.gen.yaml). It demonstrates all HTTP verbs (GET, POST, PUT, PATCH, DELETE), path and query parameters, and request validation. The example includes several Go client usage files (client\_example.go, client\_content\_types.go, client\_error\_handling.go, client\_per\_call\_options.go) showing how to interact with the generated API, covering basic operations, content type switching (JSON vs Protobuf), error handling, and per-request options like custom headers. Additionally, it adds automated regression tests (test\_accept\_header.sh, test\_path\_params.sh) to verify correct Accept header negotiation and path parameter preservation during body unmarshaling.

examples/restful-crud · high confidence

The examples/sse-streaming directory now provides a complete demo for Server-Sent Events (SSE) streaming of market data. It includes a Go server that serves unary quote snapshots and real-time quote/trade streams, alongside generated Go and TypeScript clients that demonstrate how to consume these streams. The example is self-contained with a Makefile for building, running, and cleaning up the demo, and includes OpenAPI documentation for the generated API.

examples/sse-streaming · high confidence

Added a new \examples/ts-client-demo\ directory that provides a complete, runnable example of the TypeScript HTTP client. It includes a Go-based server (\main.go\) and a TypeScript client (\client/main.ts\) that demonstrates key client features such as typed constructor options for service headers (e.g., \apiKey\, \tenantId\), CRUD operations (GET, POST, PUT, PATCH, DELETE), query parameter filtering, pagination, and handling of discriminated-union oneofs in the generated types. The example is configured via \buf.gen.yaml\ to generate both Go server handlers and TypeScript client code using the \protoc-gen-go-http\ and \protoc-gen-ts-client\ plugins.

examples/ts-client-demo · high confidence

The examples/ts-fullstack-demo directory now provides a complete TypeScript reference implementation, including a generated HTTP server, a typed client, and a browser-based UI. Users can run the demo via Makefile targets (e.g., make demo) to generate code from proto definitions using protoc-gen-ts-server and protoc-gen-ts-client, start the server, and interact with the API through both a terminal client and a web UI that logs requests/responses and exposes CRUD operations for notes.

examples/ts-fullstack-demo · high confidence

A new protoc plugin (cmd/protoc-gen-ts-client) has been added to generate TypeScript HTTP clients for Protobuf services. Users can now configure the generated code to use either the 'protobuf-es' runtime or a 'hand-rolled' implementation via the ts\_runtime parameter, and choose between 'throw' or 'result' based error handling via the ts\_error\_handling parameter. The generator explicitly supports proto3 optional fields.

cmd/protoc-gen-ts-client · high confidence

The \internal/tscommon\ package now provides the core generation logic for the new TypeScript client/server generators. It introduces support for the \protobuf-es\ runtime mode (via the \ts\_runtime=protobuf-es\ option), which generates code using the \@bufbuild/protobuf\ runtime instead of hand-rolled serialization. Additionally, it adds a \ts\_error\_handling=result\ option that changes client methods to return a discriminated \Result\ union (\{ ok, data } \| { ok, error }\) instead of throwing on failure. The package also includes a validation layer (\CheckESMessageAnnotations\) that fails generation if the proto uses JSON-mapping annotations (like \unwrap\ or \flatten\) that are not supported by the canonical \protobuf-es\ codec, ensuring wire compatibility with the Go server. Finally, it implements a robust import tracking system to handle module resolution, symbol aliasing, and global name reservation for the generated TypeScript modules.

internal/tscommon · high confidence

Added the \examples/marshal-options\ directory, which provides a runnable demo of the \WithMarshalOptions\ server registration option. This example illustrates how to configure \protojson.MarshalOptions\ (specifically \EmitUnpopulated: true\) to surface proto3 zero values in JSON responses, contrasting default behavior with explicit marshaling configuration via two side-by-side HTTP servers.

examples/marshal-options · high confidence

Added a new example in \examples/multi-service-api\ that showcases organizing multiple services with different authentication requirements in a single API. The example includes a PublicService (no auth), a UserService (requiring Authorization and X-Tenant-ID headers), and an AdminService (requiring Authorization and X-Admin-Role headers, plus method-specific headers like X-Confirm-Delete). It also demonstrates origin-level OpenAPI bundle generation via \buf.gen.yaml\ and includes a Makefile with targets to generate code, run the server, and test various authentication scenarios.

examples/multi-service-api · high confidence

This release introduces the \protoc-gen-py-client\ Go binary, a protocol buffer code generator that produces Python HTTP clients from \.proto\ definitions. The generator supports typed client options for service-level headers (such as \X-API-Key\ and \X-Tenant-ID\) and method-level call options (including \X-Request-ID\ and idempotency keys). It handles various JSON mapping annotations, including custom timestamp formats (RFC3339, UNIX, date-only), int64 encoding (string vs. number), bytes encoding (base64 vs. hex), field flattening, oneof discriminators, and root unwrapping. To demonstrate these capabilities, three end-to-end demo applications are added: \python-client-demo\ (CRUD operations), \python-encoding-demo\ (wire-format round-trips), and \python-errors-demo\ (typed error handling like \NotFoundError\ and \ValidationError\).

(repo-wide) · high confidence

A new \internal/annotations\ package has been introduced to centralize the parsing of custom protobuf annotations (such as \http\_config\, \flatten\, \oneof\_discriminator\, \nullable\, \empty\_behavior\, \bytes\_encoding\, \int64\_encoding\, \enum\_encoding\, \timestamp\_format\, \field\_examples\, \headers\, \query\, and \unwrap\) previously duplicated across generators. This package provides a unified, convention-based API for extracting HTTP configuration, path parameters, query parameters, and field metadata from \.proto\ definitions, ensuring consistent behavior across all protoc plugins (httpgen, clientgen, tsclientgen, openapiv3) and adding validation for annotation usage.

internal/annotations · high confidence

Added two new shell scripts to the project: \scripts/run\_tests.sh\ provides a comprehensive test execution environment with support for fast mode, verbose output, per-package coverage analysis against an 85% threshold, race detection, and HTML/JSON report generation; and \scripts/generate\_openapi\_golden\_files.sh\ automates the building of the \protoc-gen-openapiv3\ plugin and generates YAML and JSON golden files for a set of predefined proto files to support plugin testing.

scripts · high confidence

The OpenAPI v3 generator now supports an origin-level bundle mode that merges paths and schemas from every service in a protoc invocation into a single document, controlled via \bundle=true\ and \bundle\_only\ options. This location also introduces a multi-tier testing strategy—including unit tests, integration tests, and exhaustive golden file regression tests—to ensure output correctness across YAML and JSON formats, while fixing schema generation for wrapper types, timestamps, and int64/uint64 fields to align with proto3 JSON specifications.

internal/openapiv3 · high confidence

The HTTP code generator now respects new \sebuf\ annotations to customize JSON serialization for specific field types. \bytes\_encoding\ allows bytes fields to be serialized as HEX, BASE64, or BASE64URL instead of the default standard Base64. \int64\_encoding=NUMBER\ enables int64 and uint64 fields to be emitted as native JSON numbers (with a TypeScript type of \number\ and an OpenAPI \integer\ type) rather than quoted strings, including transitive support for nested messages across files. \enum\_encoding\ supports custom string mappings for enum values and allows enums to be serialized as integers. Additionally, \empty\_behavior\ controls how empty message fields are handled, allowing them to be omitted, preserved, or explicitly serialized as \null\ (represented as a \oneOf\ schema in OpenAPI).

internal/httpgen · high confidence

The \internal/tsclientgen\ package now supports a new \protobuf-es\ runtime mode alongside the existing hand-rolled client. In this mode, the generator emits standalone, tree-shakeable functions per RPC rather than a class-based client, and it enforces stricter validation by rejecting enum-typed URL parameters and messages with unsupported JSON-mapping annotations at generation time. Additionally, a new \Result\ error-handling mode allows TypeScript clients to return typed \Result\ unions instead of throwing exceptions, with dedicated shared modules for error types and decoding. The generator also adopts a modular output structure, emitting per-proto type modules, a shared errors module, and per-package barrel files to improve import organization.

internal/tsclientgen · high confidence

The simple-api example has been reorganized to use cross-package Protocol Buffers, splitting definitions into distinct model and service files. New proto files define the User model (including validation rules and HTTP field examples) and the UserService with specific API routes for creating users, retrieving users, and handling login with multiple authentication methods (email, token, social). This structure separates data models from service interfaces, improving clarity for users studying the example's API design.

examples/simple-api/proto · high confidence

The golden test fixtures in the Go client generator have been updated to include new service examples such as backward compatibility, bytes encoding, complex features, empty behavior, empty request body, enum encoding, nested enums, flattening, and comprehensive HTTP verbs. These generated client files now support additional configuration options, including the ability to set default and per-call content types, add default headers, and configure whether to discard unknown fields in JSON responses. The updates also reflect fixes for handling enum fields in query and path parameters, proper content-type response headers, and consistent handling of empty-body RPCs across generators.

internal/clientgen/testdata/golden · high confidence

The generated Go HTTP server and client now correctly apply custom \enum\_value\ strings (e.g., "low", "call") to annotated enums at every nesting depth. Previously, while direct enum fields were serialized correctly, nested enums (such as \OptionType\ inside \OptionsContract\) would fall back to raw proto names (e.g., \OPTION\_TYPE\_CALL\). This fix ensures that both request parsing and response serialization handle custom enum strings consistently, whether the enum is a direct field or deeply nested within the message structure.

examples/enum-encoding · high confidence

The enum-params example now demonstrates that enum fields can be used as query and path parameters in HTTP requests. Users can pass enum values by name (e.g., \timeframe=TIMEFRAME\_1D\) or by number (e.g., \timeframe=3\). The example also supports repeated enum query parameters (e.g., \?class=ASSET\_CLASS\_EQUITY&class=ASSET\_CLASS\_CRYPTO\) and validates that invalid enum values return a 400 error. This includes regression tests for issues \#151 and \#186.

examples/enum-params · high confidence

The generated Go HTTP server test fixtures in \internal/httpgen/testdata/golden\ have been updated to reflect several internal code generation fixes. Request body binding now occurs before path and query parameter binding for POST/PUT/PATCH methods to prevent \proto.Reset\ from wiping fields, ensuring URL parameters take precedence. Response content type negotiation now strictly follows RFC 9110 by prioritizing the \Accept\ header, falling back to \Content-Type\, and defaulting to JSON. Additionally, the generated server configuration now supports \WithMarshalOptions\ to pass \protojson.MarshalOptions\ (such as \EmitUnpopulated\) through custom marshalers, and includes updated golden files for features like \int64\ NUMBER encoding, bytes encoding, empty behavior, and unwrap semantics.

internal/httpgen/testdata/golden · high confidence

Added TypeScript client golden files and protobuf-es wire-conformance tests; Added TypeScript server generator test fixtures and wire-conformance proof; Expanded OpenAPI v3 test fixtures for comprehensive protocol coverage; Expanded test coverage for client generation edge cases; Expanded test fixtures for HTTP code generation edge cases.

The project now includes a root \go.mod\ file defining the module \github.com/SebastienMelki/sebuf\ with Go 1.26, requiring \github.com/pb33f/libopenapi v0.38.7\, \go.yaml.in/yaml/v4 v4.0.0-rc.6\, and \google.golang.org/protobuf v1.36.11\. Additionally, \go.mod\ and \go.sum\ files have been added for all example directories (such as \enum-encoding\, \simple-api\, \ts-client-demo\, and \rn-client-demo\), establishing their specific dependency trees and setting up the local \sebuf\ module replacement.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 79 → 70 (-9.5)
• Rubric changed (rubric-2026.09.15 → rubric-2026.10.1) — scores are not directly comparable.

• Code Health 100 → 94 (-5.8)
• Architecture 100 → 88 (-12.3)
• Maturity 79 → 79 (-0.1)
• Readiness 80 → 58 (-22.4)
• Security 73 → 77 (+3.3)
• Performance 82 (new)

• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)

• ClassTooLong: Generator (internal/clientgen/generator.go)
• ClassTooLong: Generator (internal/httpgen/generator.go)
• ClassTooLong: Generator (internal/openapiv3/generator.go)
• ClassTooLong: Generator (internal/tsclientgen/generator.go)
• ClassTooLong: Generator (internal/tsservergen/generator.go)
• Documentation: no project overview (README.md)
• Duplicated block (10 lines × 2) (examples/error-handler/main.go)
• Duplicated block (10 lines × 2) (internal/httpgen/enum_field_encoding.go)
• Duplicated block (10 lines × 2) (internal/httpgen/unwrap.go)
• Duplicated block (10 lines × 6) (internal/httpgen/bytes_encoding.go)
• Duplicated block (11 lines × 2) (internal/httpgen/bytes_encoding.go)
• Duplicated block (11 lines × 2) (internal/httpgen/generator.go)
• Duplicated block (11 lines × 2) (internal/tscommon/types.go)
• Duplicated block (11 lines × 3) (examples/python-client-demo/main.go)
• Duplicated block (11 lines × 6) (internal/httpgen/bytes_encoding.go)
• Duplicated block (11–14 lines × 2) (internal/tscommon/modules.go)
• Duplicated block (13 lines × 2) (examples/python-client-demo/main.go)
• Duplicated block (13 lines × 2) (examples/python-client-demo/main.go)
• Duplicated block (13 lines × 2) (examples/python-client-demo/main.go)
• Duplicated block (13 lines × 2) (internal/httpgen/encoding.go)
• …and 103 more

• 0 containers · 1 bounded contexts · 0 dependency edges (baseline)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

SebastienMelki/sebuf was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.