GitHub Releases NuGet v1.0.0 MIT

metaengine-graphql-go-nethttp

GraphQL SDL → an idiomatic Go net/http client and structs with typed queries, mutations & subscriptions (subscriptions surface as (<-chan T, <-chan error) over a graphql-transport-ws WebSocket via github.com/coder/websocket), plus bearer/basic auth, retries, timeouts, error handling, fragments, and @oneOf inputs. context.Context-first methods and *T pointers for optional fields by default. Delivered as a self-contained single binary — no .NET runtime required.

GraphQL SDLMetaEngine IRGo · 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-graphql-go-nethttp
$go install github.com/meta-engine/metaengine-graphql-go-nethttp@latest
v1.0.0
NuGetMetaEngine.Go.GraphQL.NetHttp
$dotnet add package MetaEngine.Go.GraphQL.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-graphql-go-nethttp <input> <output> <module> <package> [flags]

Generates an idiomatic Go net/http client and structs from a GraphQL SDL schema — typed queries, mutations & subscriptions. Queries and mutations travel over HTTP POST; subscriptions resolve to (<-chan T, <-chan error) over a graphql-transport-ws WebSocket (github.com/coder/websocket), with the WebSocket URL passed to the client constructor at runtime. <input> is a GraphQL schema file path (SDL); <module> is the Go module name (e.g. github.com/acme/api) and <package> the Go package name (e.g. client). Methods take a context.Context and use *T pointers for optional fields by default. Ships as a self-contained single binary — no .NET runtime required.

Quick examples
Docs, smart error handling and retries
metaengine-graphql-go-nethttp schema.graphql ./client github.com/acme/api client --documentation --error-handling --retries 3
Bearer auth, a request timeout and a custom header
metaengine-graphql-go-nethttp schema.graphql ./client github.com/acme/api client --bearer-auth API_TOKEN --timeout 30 --header X-Tenant-ID:TENANT_ID
Fragments, @oneOf inputs and validate struct tags
metaengine-graphql-go-nethttp schema.graphql ./client github.com/acme/api client --fragments --oneof-inputs --validate-struct-tags
CLI options
Option
Description
--documentation
Generate Go doc comments (carries GraphQL schema descriptions through)
--options-threshold <n>
Parameter count at which a method switches to an options struct (default: 4)
--validate-struct-tags
Add validate struct tags to generated models
--timeout <seconds>
HTTP client timeout in seconds
--base-url-env <name>
Read the base URL from this env var at runtime (default: API_BASE_URL)
--bearer-auth <env>
Bearer-token auth; the token is read from this env var
--bearer-header <name>
Custom header name for the bearer token (use with --bearer-auth)
--basic-auth <userEnv:passEnv>
Basic auth; username/password read from these env vars
--retries [n]
Retry failed requests with exponential backoff, 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
--error-handling
Map HTTP error status codes to Go errors (>= 400 → typed *HTTPStatusError)
--throw-for <codes>
Return a formatted error (HTTP <code>: <body>) for these status codes (comma-separated); implies --error-handling
--return-null-for <codes>
Return the ErrNullResponse sentinel for these status codes (comma-separated); implies --error-handling
--return-error-for <codes>
Return a typed *HTTPStatusError for these status codes (comma-separated); implies --error-handling
--fragments
Generate reusable fragment types
--oneof-inputs
Honor @oneOf on input types (exactly-one-field inputs)
--clean
Remove stale files from the output directory before writing
--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

6
  • WithDocumentation()Generate Go doc comments on methods and types, carrying GraphQL SDL descriptions through
  • WithValidateStructTags()Emit validate:"required" struct tags on non-null fields of generated models
  • WithContext()context.Context as the first method parameter (engine default; the CLI exposes no opt-out)
  • WithPointersForOmittable()Use *T pointers for optional fields so omitted vs. zero is distinguishable (engine default)
  • WithMethodNames(Func)Custom method naming rule with access to operation context
  • WithOptionsObjectThreshold(int)Parameter count at which a method switches to an options struct (default: 4)

Auth · Headers · Resilience

15
  • WithErrorHandling()Smart error handling based on HTTP status (404 / 403 → ErrNullResponse sentinel · 400 / 422 → error body · 401 / 5xx → typed *HTTPStatusError). GraphQL queries/mutations travel over HTTP POST.
  • WithErrorHandling(errors => errors...)Per-status routing via handleResponse: ReturnNullFor(404, 403) · ReturnErrorFor(400, 422) · ThrowFor(401, 500)
  • WithBearerAuth()Bearer token from env var (default API_TOKEN) — adds an Authorization header
  • WithBearerAuth(string)Bearer token from a specific env var name
  • WithBearerAuth(string, string)Bearer token from an env var with a custom header name (e.g. X-Api-Key)
  • WithBasicAuth()HTTP Basic auth from default env vars (API_USERNAME / API_PASSWORD)
  • WithBasicAuth(string, string)HTTP Basic auth from username + password env vars
  • WithCustomHeader(string, string)Static header sourced from an env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
  • WithBaseUrlEnvVar(string)Read the base URL from an env var at runtime (default API_BASE_URL)
  • WithTimeout(double)Request timeout in seconds for all operations
  • WithTimeout(double?, double?, double?, double?)Granular timeout: connect · read · write · pool (seconds)
  • WithRetries()Retries with exponential backoff over retryable status codes (default 429, 503)
  • WithRetries(int)Retries with a custom max-attempts count
  • WithRetries(int, double, double, int[])Retries with full custom settings: max attempts · base delay · max delay · retryable status codes
  • WithMiddleware()Generate RoundTripper middleware infrastructure (a request/response hook on the client)

GraphQL Options

5
  • WithFragments()Emit reusable named fragments for object-type selections (...TypeFields spreads, hoisted into fragments.go)
  • WithOneOfInputs()Generate idiomatic @oneOf input types (tagged-union inputs where exactly one field is set)
  • WithCustomScalar(string, Type)Map a GraphQL custom scalar to a System.Type for Go resolution (e.g. DateTime → time.Time). Unmapped scalars default to string
  • WithTypeFilter(Func)Filter extracted GraphQL types before registration — only types returning true are generated
  • WithDocumentation()Carry SDL type/field descriptions through as Go doc comments

Naming Transformations

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

File Management

5
  • 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

2
  • 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.