tunneld

README

tunneld

tunneld is a thin, stable façade over stable/alpha versioned packages (v1 stable contract, v1alpha1 mutable implementation), with CI, CodeQL, OpenSSF Scorecard, cosign-signed releases, Dependabot, examples, and an e2e harness.

The API is a generic builder: New[T]() configures with With* methods and finalizes with Build().

Quick Start

go get github.com/tunnel-pizza/tunneld

package main

import (
	"fmt"

	"github.com/tunnel-pizza/tunneld"
)

func main() {
	res := tunneld.New[string]().
		WithName("greeting").
		WithValue("hello world").
		Build()

	fmt.Printf("%s: %s\n", res.Name, res.Value) // greeting: hello world
}

(Full source: examples/basic/main.go.)

Layout

Three packages, stable/alpha versioning:

github.com/tunnel-pizza/tunneld           — root façade. New, Version, and aliases for
                                   the caller-facing types.
github.com/tunnel-pizza/tunneld/v1        — stable Builder[T] interface + Result[T],
                                   the Err* sentinels, the *Env constants.
github.com/tunnel-pizza/tunneld/v1alpha1  — current implementation. May change
                                   between alpha revisions.

Application code imports only the root: tunneld.New[T]() builds, and tunneld.BuilderV1[T] / tunneld.Result[T] name the types in a field or signature. Import v1 directly to implement the interface yourself, or to reach a symbol the façade doesn't re-export. Direct access to the BuilderImpl[T] struct lives in v1alpha1.

For the file-by-file map, see CONTRIBUTING.md → Where to find things.

API at a glance

The root package — everything application code needs:

type BuilderV1[T any] = v1.Builder[T]   // alias, so callers needn't import v1
type Result[T any]    = v1.Result[T]

func New[T any]() BuilderV1[T]   // unconfigured builder
func Version() string            // the release this build links against

The contract itself, in v1:

type Builder[T any] interface {
    WithName(name string) Builder[T]   // display name carried into the Result
    WithValue(v T) Builder[T]          // the payload Build produces
    Build() Result[T]                  // terminal: assembles and returns
    Name() string                      // configured name (empty if unset)
}

type Result[T any] struct {
    Name  string `json:"name,omitempty"`
    Value T      `json:"value"`
}

var ErrInvalidEnv = errors.New("invalid environment value")  // match with errors.Is
const LogEnv = "TUNNELD_LOG"

And the env plumbing implementations use, in v1alpha1:

func EnvBool(name string) (value, fixed bool, err error)
func EnvDuration(name string) (value time.Duration, fixed bool, err error)
func Logger() *slog.Logger   // silent unless TUNNELD_LOG names a level

Environment

Every knob with an env-expressible value has a mirror constant in v1, and env beats code — an operator reconfigures a deployed binary without a rebuild. Variables are read lazily, where the knob takes effect, so a value set after construction still lands.

Variable	Effect
TUNNELD_LOG	Level (debug|info|warn|error) of v1alpha1.Logger. Unset, that logger is silent.

Names follow TUNNELD_<KNOB> for core knobs and TUNNELD__<IMPL>_<KNOB> — double underscore — for implementation-scoped ones, so two implementations can each expose a TIMEOUT without colliding.

An override that is set but unparsable is reported, never silently ignored: EnvBool and EnvDuration return an error wrapping v1.ErrInvalidEnv naming the variable and the bad value. A typo'd knob that quietly did nothing would be indistinguishable from one that worked.

Examples

Self-contained programs in ./examples:

Example	Demonstrates
basic	Smallest wiring — New + WithValue + Build.
named	A typed struct payload carried through WithValue.

Run one locally:

make run basic
make run named

Testing

make test   # library unit + fuzz tests (fast, in-package)
make e2e    # builds and runs every example binary, asserts its output
make race   # every package under the race detector — the lane CI gates on

make e2e runs go test -count=1 -v ./e2e. The -count=1 defeats the test cache, since the harness builds the example binaries at runtime and the cache key wouldn't otherwise pick up example source changes.

Contributing

See CONTRIBUTING.md for the local dev loop, release process, and what makes a good example.

License

MIT

Documentation

Overview

Package tunneld is a thin, stable façade over stable/alpha versioned packages.

The package is split into three pieces:

• tunneld (this package) — thin façade exposing New, Version, and aliases for the caller-facing types. Stable surface for application code.
• github.com/tunnel-pizza/tunneld/v1 — the stable Builder[T] interface and Result type, plus the Err* sentinels and *Env constants. Application code normally reaches these through the aliases here; import v1 directly to implement the interface or to reach a symbol the façade doesn't re-export.
• github.com/tunnel-pizza/tunneld/v1alpha1 — the current implementation. Internals (BuilderImpl, helpers) may change between alpha revisions; pin only if you need direct access to the struct.

New[T]() returns a Builder[T] you configure with With* methods and finalize with Build().

Index

• func Version() string
• type BuilderV1
  • func New[T any]() BuilderV1[T]
• type Result

Functions

func Version

func Version() string

Version reports the tunneld release this build links against — e.g. "v0.0.5". It matches the git tag, so a consumer can log or report the exact library version it compiles against.

Resolution, in order: the release stamp (set only in a build that passes the ldflag); the module version recorded in the importer's build info (the common consumer case — the version required in their go.mod, following a replace directive if one redirects it); the main-module version; and finally the short VCS revision of a local build, with a -dirty suffix for an uncommitted tree. A build carrying no version information at all returns "unknown", never the empty string — Version always self-identifies.

Types

type BuilderV1

type BuilderV1[T any] = v1.Builder[T]

BuilderV1 is the builder returned by New: an alias for v1.Builder[T], re-exported so callers can name the type without importing v1. The V1 suffix versions the root name — when a v2 contract lands, BuilderV2 can sit beside this one in the same façade and callers migrate type by type instead of all at once. Alias, not a defined type: the two spellings are the same type, so a v1.Builder[T] from anywhere satisfies a BuilderV1[T] and back.

func New

func New[T any]() BuilderV1[T]

New returns an unconfigured Builder for values of type T. Configure it with the With* methods, then call Build.

res := tunneld.New[string]().WithName("greeting").WithValue("hello").Build()

type Result

type Result[T any] = v1.Result[T] // structured output of Build: Name + Value

The supporting types, re-exported from v1 so application code imports only the root package. These are unversioned: they are data carried across the contract rather than the contract itself, so a v2 that keeps them keeps these names.