GitHub Releases NuGet v1.0.0 MIT

metaengine-protobuf-go-nethttp

Protobuf 3 → an idiomatic Go net/http client and message structs over gRPC-Connect, with context.Context methods, pointer types for optional fields, and typed Connect protocol errors (no HTTP-status routing). Delivered as a self-contained single binary — no .NET runtime required.

Protobuf 3.x

MetaEngine IR

Go · net/http

Install

Pick your registry

The same generator, published to every ecosystem we support. Install however your project expects.

GitHub ReleasesPrimarygithub.com/meta-engine/metaengine-protobuf-go-nethttp

$go install github.com/meta-engine/metaengine-protobuf-go-nethttp@latest

v1.0.0

NuGetMetaEngine.Go.Protobuf.NetHttp

$dotnet add package MetaEngine.Go.Protobuf.NetHttp

v1.0.0

Usage

Drive it from the CLI or programmatically

GitHub Releases ships a zero-config CLI. NuGet ships the same generator as a C# fluent API — same options, same output.

GitHub Releases · go install / brew · CI-friendly

After install, point the CLI at your schema. It writes the generated tree to your chosen output directory.

Basic syntax

terminal

metaengine-protobuf-go-nethttp <input> <output> <module> <package> [flags]

Generates an idiomatic Go net/http gRPC-Connect client and message structs from Protobuf 3 .proto files. Ships as a self-contained single binary (go install / brew / shell) — no .NET runtime required.

Quick examples

Generate from a .proto file

metaengine-protobuf-go-nethttp service.proto ./client github.com/acme/api client

With doc comments and retries

metaengine-protobuf-go-nethttp service.proto ./client github.com/acme/api client \
  --documentation \
  --retries 3

Bearer auth + custom header, clean output

metaengine-protobuf-go-nethttp service.proto ./client github.com/acme/api client \
  --bearer-auth API_TOKEN \
  --header X-Tenant-ID:TENANT_ID \
  --clean \
  --verbose

CLI options

Option

Description

--documentation

Generate Go doc comments

--timeout <seconds>

Default HTTP timeout in seconds

--base-url-env <name>

Read the base URL from this environment variable at runtime

--bearer-auth <env>

Enable bearer auth; the token is read from this environment variable

--bearer-header <name>

Custom header name for the bearer token (use with --bearer-auth)

--basic-auth <userEnv:passEnv>

Enable basic auth; username/password read from these environment variables

--retries [n]

Retry failed requests, optionally capping at n attempts

--header <name:env>

Custom request header sourced from an env var (repeatable)

--middleware

Generate a request/response middleware hook on the client

--clean

Clean the output directory before generating

--verbose

Enable verbose logging

Options reference

Every knob, documented

Every option is available on the C# fluent API as a method, and most are also exposed as CLI flags. Cross-cutting auth, headers, retries and timeouts apply across frameworks.

Go Options

WithDocumentation()Generate Go doc comments on structs and service methods
WithContext()Take context.Context as the first parameter on every method (idiomatic Go; on by default)
WithPointersForOmittable()Generate *T pointer types for optional fields so absence is distinguishable from the zero value
WithValidateStructTags()Emit validate:"…" struct tags for github.com/go-playground/validator (off by default — no implicit third-party dependency)
WithMethodNames(Func)Custom method naming rule with access to operation context
WithOptionsObjectThreshold(int)Parameter count before an options struct is used (default: 4)

Auth · Headers · Resilience

WithMiddleware()Generate RoundTripper middleware infrastructure (Middleware type + ChainMiddleware + NewHTTPClientWithMiddleware)
WithBearerAuth()Bearer token from env var (default API_TOKEN) — adds an Authorization header at the transport layer
WithBearerAuth(string)Bearer token from a specific env var name
WithBearerAuth(string, string)Bearer token with a custom header name (e.g. X-Api-Key)
WithBasicAuth(string, string)HTTP Basic auth — username + password read from these env vars (defaults API_USERNAME / API_PASSWORD)
WithCustomHeader(string, string)Static header sourced from an env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
WithBaseUrlEnvVar(string)Environment variable name for the base URL, read at runtime (default: API_BASE_URL)
WithTimeout(double)Request timeout in seconds for all operations (sets the net/http client timeout)
WithTimeout(double?, double?, double?, double?)Granular timeout: connect · read · write · pool (null = use default)
WithRetries()HTTP retries with exponential backoff over connectUnary (default status 429, 503)
WithRetries(int)Retries with a custom max attempt count
WithRetries(int, double, double, int[])Retries with max attempts, base delay (s), max delay (s), and custom retryable status codes

Protobuf Options

WithTypeFilter(Func)Filter extracted proto types (messages + enums) before registration — only types returning true are generated
WithTypeMapping(string, Type)Override the protobuf well-known-type mapping by fully-qualified name (e.g. google.protobuf.Timestamp → string)

Naming Transformations

Types(Func)Transform type names
Paths(Func)Transform output paths
FileNames(Func)Transform file names

File Management

CleanDestination()Clean output directory before generation
AlwaysOverwrite()Always overwrite existing files
OnlyWhenModelChanged()Update only when model changes
OnlyWhenNew()Write only new files, preserve existing
CleanDirectories(...)Clean specific subdirectories

Diagnostics

Verbose()Enable verbose logging
WithLogger(Action<string>)Route generation log output to a custom sink

Features

Why this package is different

Deterministic output

Same spec + same options produce byte-identical files. Safe to commit, safe to diff in review, safe to cache in CI.

Flexible naming

Case conventions are configurable per role — types, properties, operations, enums. Idiomatic in the target by default.

Semver-honest

Spec diff drives the version bump. Additive changes = minor, removed operations = major. Never a surprise in your lockfile.