t3relay

package module
v0.0.0-...-a1665f6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 28, 2026 License: MIT Imports: 43 Imported by: 0

README

t3code-devcontainer-relay module

A Caddy v2 module that discovers devcontainers via Docker labels, stores them in SQLite, and provides:

  • Proxy handler (http.handlers.t3code_relay_proxy): authenticates Bearer tokens, resolves Host to a container IP via the store, and reverse-proxies the request.
  • API handler (http.handlers.t3code_relay_api): provides /health, /v1/environments, per-environment /status and /connect, DELETE /v1/environments/:id for forgetting stale rows, and the relay mount browser at /mounts.

Caddyfile global option

{
  t3code_relay {
    domain_suffix       t3.example.com
    relay_host          relay.t3.example.com
    db_path             /var/lib/t3relay/relay.db
    docker_host         unix:///var/run/docker.sock
    probe_port          3773
    tokens              tok1,tok2
    shared_secret_file  /run/secrets/relay_secret
    mounts_root         /mnt/t3relay
  }
}

Mounted file browser

The relay serves a browser UI from https://relay.t3.<domain>/mounts. The UI is public HTML, but file tree and file content endpoints require a configured relay bearer token.

  • GET /v1/mounts/tree returns root metadata for mounts_root.
  • GET /v1/mounts/children?path=<path> lazily returns one directory level.
  • GET /v1/mounts/file/<path>?mode=render|source returns rendered content or source.
  • .html files render as sandboxed HTML, .md/.markdown files render to HTML, and common image types render as images.
  • Non-binary files can be viewed as source with Prism syntax highlighting, line numbers, and linkable line numbers.

Running tests

go test ./...

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIHandler

type APIHandler struct {
	// contains filtered or unexported fields
}

APIHandler implements the relay control-plane API at relay.t3.<domain>.

Caddy module: http.handlers.t3code_relay_api

func (*APIHandler) CaddyModule

func (*APIHandler) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (*APIHandler) Provision

func (a *APIHandler) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*APIHandler) ServeHTTP

func (a *APIHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (*APIHandler) UnmarshalCaddyfile

func (a *APIHandler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler (no-op).

type Environment

type Environment struct {
	ID          string // devcontainer.id label value
	ContainerID string
	Name        string // sanitized name
	Hostname    string // <name>.<domain_suffix>
	IP          string
	Port        int
	Status      string // running | unreachable | stopped
	ProbeJSON   string // raw JSON from probe
	FirstSeen   int64  // unix seconds
	LastSeen    int64  // unix seconds
}

Environment represents a discovered devcontainer environment.

type Exposure

type Exposure struct {
	EnvironmentID string
	Name          string
	HostLabel     string
	Scheme        string
	Port          int
	CreatedAt     int64
	LastSeen      int64
	ExpiresAt     int64
}

type ProxyHandler

type ProxyHandler struct {
	// contains filtered or unexported fields
}

ProxyHandler is the HTTP middleware handler for per-environment proxying. It resolves Host → container IP via the app's store and reverse-proxies.

Caddy module: http.handlers.t3code_relay_proxy

func (*ProxyHandler) CaddyModule

func (*ProxyHandler) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (*ProxyHandler) Provision

func (p *ProxyHandler) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*ProxyHandler) ServeHTTP

func (p *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (*ProxyHandler) UnmarshalCaddyfile

func (p *ProxyHandler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler (no-op, no config needed).

type RelayApp

type RelayApp struct {
	// DomainSuffix is the legacy/default base domain suffix, e.g. "t3.example.com".
	// When wildcard Caddy labels are present on the relay container, those labels
	// become the source of truth for served zones and this value is used only as a
	// fallback/default.
	DomainSuffix string `json:"domain_suffix,omitempty"`
	// RelayHost is the legacy/default relay API hostname, e.g. "relay.t3.example.com".
	RelayHost string `json:"relay_host,omitempty"`
	// DBPath is the file path to the SQLite database.
	DBPath string `json:"db_path,omitempty"`
	// DockerHost is the Docker socket or TCP address.
	DockerHost string `json:"docker_host,omitempty"`
	// ProbePort is the port to probe on each devcontainer (default 3773).
	ProbePort int `json:"probe_port,omitempty"`
	// Tokens is the comma-separated list of bearer tokens.
	Tokens string `json:"tokens,omitempty"`
	// SharedSecretFile is the path to the file containing the shared secret.
	SharedSecretFile string `json:"shared_secret_file,omitempty"`
	// TailscaleHostname is the hostname presented by the embedded tsnet node.
	TailscaleHostname string `json:"tailscale_hostname,omitempty"`
	// TailscaleAuthKey is the auth key used to join the tailnet.
	TailscaleAuthKey string `json:"tailscale_auth_key,omitempty"`
	// TailscaleStateDir is the directory used to persist tsnet state.
	TailscaleStateDir string `json:"tailscale_state_dir,omitempty"`
	// SSHHostKeyFile is the persisted private host key for the tailnet SSH gateway.
	SSHHostKeyFile string `json:"ssh_host_key_file,omitempty"`
	// SSHAllowedUser is the only username accepted by the tailnet SSH gateway.
	SSHAllowedUser string `json:"ssh_allowed_user,omitempty"`
	// SSHBackendPort is the port the devcontainer sshd feature listens on.
	SSHBackendPort int `json:"ssh_backend_port,omitempty"`
	// MountsRoot is the directory whose contents are exposed by the relay mount browser.
	MountsRoot string `json:"mounts_root,omitempty"`
	// contains filtered or unexported fields
}

RelayApp is the Caddy app that manages Docker discovery, SQLite store, and exposes accessor methods to the two HTTP handler modules.

func (*RelayApp) CaddyModule

func (*RelayApp) CaddyModule() caddy.ModuleInfo

CaddyModule implements caddy.Module.

func (*RelayApp) GetDocker

func (a *RelayApp) GetDocker() *dockerclient.Client

GetDocker returns the Docker client (used by discovery and API handler for live probes).

func (*RelayApp) GetStore

func (a *RelayApp) GetStore() *Store

GetStore returns the underlying store (used by API handler for direct lookups).

func (*RelayApp) ListEnvironments

func (a *RelayApp) ListEnvironments() []Environment

ListEnvironments returns all environments from the store.

func (*RelayApp) LookupByHost

func (a *RelayApp) LookupByHost(hostname string) (Environment, bool)

LookupByHost returns an environment by parsing a served hostname and resolving its left-hand environment label.

func (*RelayApp) LookupExposureByHost

func (a *RelayApp) LookupExposureByHost(hostname string) (Environment, Exposure, bool)

func (*RelayApp) ParseServedHost

func (a *RelayApp) ParseServedHost(host string) (name, zone string, ok bool)

ParseServedHost parses a public host of the form <name>.<served-zone>.

func (*RelayApp) ProbePortNum

func (a *RelayApp) ProbePortNum() int

ProbePortNum returns the configured probe port.

func (*RelayApp) Provision

func (a *RelayApp) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (*RelayApp) PublishedHostname

func (a *RelayApp) PublishedHostname(name string) string

PublishedHostname returns the canonical published hostname for an environment.

func (*RelayApp) ResolveSSHForwardTarget

func (a *RelayApp) ResolveSSHForwardTarget(host string, port int) (Environment, error)

func (*RelayApp) SharedSecret

func (a *RelayApp) SharedSecret() []byte

SharedSecret returns the loaded shared secret bytes.

func (*RelayApp) Start

func (a *RelayApp) Start() error

Start implements caddy.App.

func (*RelayApp) Stop

func (a *RelayApp) Stop() error

Stop implements caddy.App.

func (*RelayApp) SupportedZones

func (a *RelayApp) SupportedZones() []string

SupportedZones returns the served wildcard zones discovered from Caddy labels.

func (*RelayApp) UnmarshalCaddyfile

func (a *RelayApp) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler (not needed for global option, kept for completeness/testing).

func (*RelayApp) ValidateBearer

func (a *RelayApp) ValidateBearer(token string) bool

ValidateBearer returns true if the token matches one of the configured tokens. Uses constant-time comparison to prevent timing attacks.

func (*RelayApp) ValidateSharedSecret

func (a *RelayApp) ValidateSharedSecret(candidate string) bool

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store manages the SQLite-backed environments table.

func OpenStore

func OpenStore(path string) (*Store, error)

OpenStore opens (creating if necessary) the SQLite DB at path.

func (*Store) Close

func (s *Store) Close() error

Close closes the underlying database.

func (*Store) DeleteByID

func (s *Store) DeleteByID(id string) (bool, error)

DeleteByID removes an environment row by its internal store ID.

func (*Store) DeleteExpiredExposures

func (s *Store) DeleteExpiredExposures() error

func (*Store) DeleteExposure

func (s *Store) DeleteExposure(environmentID, name string) (bool, error)

func (*Store) GetByHost

func (s *Store) GetByHost(hostname string) (Environment, bool)

GetByHost returns an environment by its full hostname.

func (*Store) GetByID

func (s *Store) GetByID(id string) (Environment, bool)

GetByID returns an environment by its devcontainer ID.

func (*Store) GetByName

func (s *Store) GetByName(name string) (Environment, bool)

GetByName returns an environment by its canonical published name.

func (*Store) GetExposureByHostLabel

func (s *Store) GetExposureByHostLabel(hostLabel string) (Exposure, bool)

func (*Store) List

func (s *Store) List() []Environment

List returns all environments ordered by last_seen desc.

func (*Store) ListExposures

func (s *Store) ListExposures(environmentID string) []Exposure

func (*Store) MarkStopped

func (s *Store) MarkStopped(containerID string) error

MarkStopped sets status='stopped' for the given container_id.

func (*Store) Upsert

func (s *Store) Upsert(env Environment) error

Upsert inserts or updates an environment row.

func (*Store) UpsertExposure

func (s *Store) UpsertExposure(exposure Exposure) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL