v1

type Backend[T Spec] interface {
	// Name identifies the backend (e.g. "cloudflare").
	Name() string
	// Provider is the credential chain this backend draws specs from. For
	// Cloudflare: adopt LIBTUNNEL_SPEC from the environment when present,
	// otherwise mint an anonymous quick tunnel.
	Provider() Provider[T]
	// WithTLS declares whether the local origin terminates TLS. True dials the
	// listener over https (verification is off, so a self-signed cert is fine);
	// false over http. Default false. Chainable:
	// libtunnel.Cloudflare().WithTLS(true). The LIBTUNNEL_TLS environment
	// variable (strconv.ParseBool syntax) fixes the knob at backend
	// construction and makes this call a no-op — env beats code; an
	// unparsable value fails the tunnel at connect.
	WithTLS(bool) Backend[T]
	// WithHTTP2 declares whether the origin is dialed over HTTP/2 rather than
	// HTTP/1.1. Independent of WithTLS, though a stdlib http.Server only
	// negotiates HTTP/2 over TLS. Default false. Chainable. LIBTUNNEL_HTTP2
	// fixes it from the environment under the same rules as WithTLS.
	WithHTTP2(bool) Backend[T]
	// Reconnect forcefully cycles the engine's connection(s) to the tunnel edge
	// and blocks until the edge is re-established or ctx is done (returning
	// ctx.Err()); pass a ctx with a deadline to bound the wait. It also returns
	// if the tunnel itself shuts down while waiting. It is an error to call
	// before the tunnel has connected. This is the same lever surfaced to
	// interceptors as InterceptCtx.Reconnect.
	Reconnect(ctx context.Context) error
}

type InterceptCtx interface {
	context.Context

	// Reconnect forcefully cycles the engine's edge connection(s) and blocks
	// until re-established or ctx is done (see Backend.Reconnect).
	Reconnect(ctx context.Context) error
	// Target is the loopback listener the engine dials to reach the origin
	// proxy — the proxy's own accept socket, not the origin. An interceptor can
	// cycle it (close to force the engine to re-dial).
	Target() net.Listener

	// WithHandler replaces the handler that will serve this request and returns
	// the ctx for chaining. Unset, the handler proxies the request to the origin.
	WithHandler(h http.HandlerFunc) InterceptCtx
	// Handler is the handler currently set to serve the request.
	Handler() http.HandlerFunc

	// Writer is the response writer for the request.
	Writer() http.ResponseWriter
	// Request is the inbound request.
	Request() *http.Request
}

type InterceptFn = func(ctx InterceptCtx) InterceptCtx

type Interceptor struct {
	Match   MatchFn
	Handler InterceptFn
	// Priority orders interceptors when more than one could match, AWS-ALB style:
	// the LOWEST Priority is consulted first, so it wins. Interceptors of equal
	// Priority keep registration order.
	//
	// 0 is not a precedence — it is the zero value that means "unset". An unset
	// Priority is auto-assigned from the top of the uint16 range downward, so
	// unprioritized interceptors sit at the low-precedence end: a later-registered
	// one wins over an earlier one, and any interceptor given an explicit Priority
	// outranks them all.
	//
	// So 1 is the highest settable precedence and 65535 the lowest; larger =
	// lower precedence. To pin an interceptor above every default, give it a
	// small Priority (1); to make it a fallback, a large one.
	Priority uint16
}

type Interceptors = []Interceptor

type MatchFn = func(r *http.Request) bool

type Provider[T Spec] interface {
	Spec(ctx context.Context) (T, error)
}

type Spec interface {
	// GetHostname returns the public hostname (host or host:port) the tunnel
	// serves under.
	GetHostname() string
	// Serialize returns the spec as a tagged-envelope JSON string — the same
	// form carried by LIBTUNNEL_SPEC. The result round-trips through
	// libtunnel.From and can be dropped straight into the env var.
	Serialize() string
}

type Tunnel interface {
	// LocalPort is the origin's local port: the listener's bound port, or for
	// a URL origin (WithLocalURL) the URL's port — 443 for https and 80 for
	// http when the URL has none. Blocks until an origin is provided.
	LocalPort() int
	// LocalIP is the origin's local IP: the listener's bound IP, or for a URL
	// origin the URL's host, parsed as an IP or resolved. A listener bound to
	// an unspecified address (0.0.0.0 / ::) falls back to the outbound-route
	// IP, discovered with a UDP dial that sends no packets. Blocks until an
	// origin is provided.
	LocalIP() net.IP
	// LocalHost is the machine's hostname, truncated at the first dot.
	LocalHost() string
	// LocalURL is the local origin's URL: http://<LocalIP>:<LocalPort>/ for a
	// listener origin (always http — the origin's scheme is a backend
	// setting, WithTLS, and the public URL carries the real scheme), or the
	// provided URL itself for a URL origin, scheme intact. Blocks until an
	// origin is provided.
	LocalURL() *url.URL

	// Host is the first label of Hostname.
	Host() string
	// Hostname is the public hostname from the spec.
	Hostname() string
	// Domain is Hostname with the first label removed.
	Domain() string
	// Port is the port encoded in Hostname, or 443 when absent.
	Port() int
	// CACerts returns the trust roots the backend uses for its edge
	// connections.
	CACerts() []*x509.Certificate

	// Listener returns a tunnel-owned listener to serve on, starting the edge
	// connection on first use. With a listener provided via WithListener it
	// returns a tunnel-owned view of that one; with no origin provided it
	// mints a loopback listener (127.0.0.1:0) and adopts it, so
	// http.Serve(tun.Listener(), h) needs no net.Listen of your own.
	// Idempotent: repeated calls return the same listener. A URL origin
	// (WithLocalURL) has no listener: calling Listener then cancels the
	// tunnel and returns nil.
	//
	// Closing it closes the tunnel (Done fires, Err reports ErrClosed) — so an
	// http.Server serving on it tears the tunnel down on Shutdown/Close. To
	// restart the origin while the tunnel persists, close the original
	// listener handed to WithListener instead and rebind the same address; a
	// minted listener has no separate owner, so closing it is terminal.
	Listener() net.Listener
	// URL is https://<Hostname>/. It blocks until the hostname resolves on
	// the zone's authoritative nameservers (see HostnameReady). URL demands
	// public reachability, so like Listener it is a start trigger: with no
	// origin provided it mints a loopback listener and starts the edge
	// connection, instead of waiting on readiness that could never arrive.
	URL() *url.URL

	// HostnameReady is closed when the hostname resolves on the zone's
	// authoritative nameservers — polled directly, so recursive resolvers'
	// negative caches never delay readiness.
	HostnameReady() <-chan struct{}
	// TunnelReady is closed when the edge connection is up and the hostname
	// resolves publicly — the tunnel is reachable end to end. It is never
	// closed on failure: select on Done alongside it. Like URL it is a start
	// trigger: with no origin provided it mints a loopback listener and
	// starts the edge connection before handing back the channel.
	TunnelReady() <-chan struct{}
	// Done is closed when the tunnel fails or shuts down. Waits on TunnelReady
	// or HostnameReady should select on Done too, or a failed tunnel blocks
	// them forever.
	Done() <-chan struct{}
	// Err reports why the tunnel ended (nil while it is alive).
	Err() error

	// WithLogger sets the logger, once. Unset, the tunnel is silent — unless
	// the LIBTUNNEL_LOG environment variable names a level
	// (debug|info|warn|error); then the default logs to stderr at that level.
	// An explicit WithLogger keeps its handler either way: the environment
	// carries a level, not a sink.
	WithLogger(log *slog.Logger) Tunnel
	// WithContext threads a caller context into the tunnel, once. It does two
	// things. First, URL waits for the tunnel to be reachable end to end
	// (TunnelReady), honoring the context, instead of only for the hostname to
	// resolve — and returns nil if the context is done first. Unset (or nil),
	// URL waits on DNS alone. Second, the context is the tunnel's shutdown
	// handle: canceling it tears the tunnel down (Done fires, Err reports the
	// context's cause) — the teardown a WithLocalURL origin otherwise lacks.
	WithContext(ctx context.Context) Tunnel
	// WithListener provides the local origin as a listener and lazily starts
	// the edge connection. The origin scheme is not inferred from the
	// listener — declare it on the backend with WithTLS / WithHTTP2 (both
	// default false).
	//
	// The origin is provided exactly once, shared with WithLocalURL and the
	// start-trigger mint. Providing it again — a second WithListener or
	// WithLocalURL, or either after a start trigger (Listener, URL,
	// TunnelReady) minted a listener — cancels the tunnel (Err reports
	// "origin already provided"). To let the tunnel supply the listener
	// instead, skip WithListener and call Listener().
	//
	// The LIBTUNNEL_LOCAL_URL environment variable supersedes any provide —
	// this listener, a WithLocalURL argument, or the start-trigger mint: env
	// beats code, so an operator can redirect a deployed binary's origin
	// without a rebuild. The override makes the origin a URL, with everything
	// that implies (see WithLocalURL); an invalid value cancels the tunnel.
	WithListener(l net.Listener) Tunnel
	// WithLocalURL provides the local origin as the URL of an already-running
	// local service (e.g. http://localhost:1234) and lazily starts the edge
	// connection — the cloudflared `tunnel --url` shape. Only the scheme and
	// host are used: the scheme (http or https) declares how the origin is
	// dialed, superseding the backend's WithTLS (which applies to listener
	// origins only), and anything else (path, query, user info) is dropped. A
	// nil URL, a scheme other than http/https, or an empty host cancels the
	// tunnel.
	//
	// The origin is provided exactly once — see WithListener, including the
	// LIBTUNNEL_LOCAL_URL environment override, which supersedes this
	// argument too. A URL origin has no tunnel-owned listener: Listener must
	// not be called (it cancels the tunnel), and Close is not the teardown
	// path. To shut a URL-origin tunnel down, set a context with WithContext
	// and cancel it; otherwise it runs until the process exits or the tunnel
	// fails.
	WithLocalURL(u *url.URL) Tunnel

	// WithInterceptor registers an Interceptor (a Match predicate paired with an
	// InterceptFn) in front of the in-process reverse proxy that fronts the
	// origin. For every inbound request the tunnel walks its interceptors in
	// registration order and runs the first whose Match returns true; requests
	// that match none are proxied to the origin unchanged. May be called more
	// than once to layer interceptors, and may be called after the tunnel is
	// live. Bundling the pair in one value lets callers ship reusable
	// interceptors as constructors — tun.WithInterceptor(addHeaders()). Returns
	// the tunnel for chaining.
	WithInterceptor(interceptor Interceptor) Tunnel

	// Interceptors returns a snapshot of the registered interceptors in
	// precedence order — ascending Priority, ties in registration order, the
	// order requests are matched against. Any auto-assigned Priority (from a
	// zero-Priority registration) is resolved in the returned values, for
	// visibility into the effective ordering.
	Interceptors() Interceptors
}