trek

Control plane server for Trek — targeted, time-bounded debug logging.

Overview

Trek enables targeted debug logging: increase logging verbosity for a narrow slice of traffic (user, request, tenant, route) without changing global log levels, with safety guardrails (TTL, caps, audit).

This repo contains the control plane server. For the SDK and CLI, see related repos below.

Features

• Debug sessions: Create time-bounded rules that target specific traffic
• Shared sessions: Sessions propagate to all service instances via polling
• RBAC: Granular permissions (session:create, token:read, policy:write, etc.)
• Audit trail: Track who enabled debugging and why
• Policy enforcement: Max TTL, required reason, allowed selectors
• Notifications: Slack/webhook alerts on session lifecycle and policy changes
• Global caps: Redis-backed per-session caps across instances
• Structured errors: Consistent {error_code, message, details} format

Quick Start

Using Docker Compose (recommended)

# Start Postgres, Redis, and Trek server
./scripts/docker-up.sh

# Run migrations and seed demo data
./scripts/migrate.sh
./scripts/seed.sh

# Verify it's running
curl http://localhost:8080/health

Manual Setup

# 1. Start Postgres
docker run -d --name trek-db -e POSTGRES_DB=trek -e POSTGRES_USER=trek -e POSTGRES_PASSWORD=trek -p 5432:5432 postgres:16

# 2. Run migrations
psql postgres://trek:trek@localhost:5432/trek -f db/migrations/001_initial.up.sql

# 3. Seed demo data
psql postgres://trek:trek@localhost:5432/trek -f db/scripts/seed.sql

# 4. Run the server
DATABASE_URL=postgres://trek:trek@localhost:5432/trek go run ./cmd/server

Development

# Run the server locally
DATABASE_URL=postgres://trek:trek@localhost:5432/trek go run ./cmd/server

# Run tests
go test ./internal/...

# Build binary
go build -o bin/trek ./cmd/server

# Before opening a PR - run full validation
./scripts/validate.sh

Pre-PR Validation

Run the validation script before opening a pull request:

./scripts/validate.sh        # Local mode (default)
./scripts/validate.sh ci     # CI mode (stricter checks)

The script runs:

• Environment check - Go version, git status
• Linting - golangci-lint with security, style, and static analysis
• Build validation - Compile all packages, check go.mod tidy
• Unit tests - Race detection, coverage report
• E2E tests - Docker-based integration tests (optional, set SKIP_E2E=false)
• Coverage check - Fails if below threshold (default 70%)
• Documentation - Validates README exists

Configuration via environment variables:

COVERAGE_THRESHOLD=80 ./scripts/validate.sh  # Custom coverage threshold
SKIP_E2E=false ./scripts/validate.sh         # Include e2e tests
TEST_TIMEOUT=10m ./scripts/validate.sh       # Custom test timeout

Configuration

Env Var	Default	Description
DATABASE_URL	required	Postgres connection string
REDIS_URL	optional	Redis for global caps
OIDC_ISSUER	optional	OIDC provider URL (Clerk)
PORT	8080	Server port

API Endpoints

Session Management (/orgs/{org}/envs/{env}/...)

Method	Path	Permission	Description
POST	/sessions	session:create	Create debug session
GET	/sessions	session:read	List sessions
GET	/active-sessions	session:read	SDK polling endpoint
POST	/sessions/{id}/revoke	session:revoke	Revoke session

Token Management (/orgs/{org}/envs/{env}/...)

Method	Path	Permission	Description
POST	/tokens	token:create	Create service token
GET	/tokens	token:read	List tokens
DELETE	/tokens/{id}	token:revoke	Revoke token

Policy & Audit (/orgs/{org}/envs/{env}/...)

Method	Path	Permission	Description
GET	/policies	policy:read	Get policy
PUT	/policies	policy:write	Update policy
GET	/audit	audit:read	Audit log

Admin APIs (/orgs/{org}/...)

Method	Path	Permission	Description
GET/POST	/envs	env:manage	Environment management
GET/POST	/users	user:manage	User management
GET/POST	/roles	role:manage	Role management
GET/POST/PUT/DELETE	/notifications	notify:manage	Notification configs

Global Caps (/orgs/{org}/envs/{env}/caps/...)

Method	Path	Permission	Description
POST	/check	session:read	Check if session blocked
POST	/increment	session:create	Increment counters
GET	/sessions/{id}	session:read	Get session cap state
DELETE	/sessions/{id}	session:revoke	Reset session counters

RBAC Permissions

Permission	Description
session:create	Create debug sessions
session:read	List/view sessions
session:revoke	Revoke sessions
token:create/read/revoke	Manage service tokens
policy:read/write	View/update policies
audit:read	View audit log
user:manage	Manage users
role:manage	Manage roles
env:manage	Manage environments
notify:manage	Manage notifications
admin	All permissions

Demo

See examples/demo/ for a sample application demonstrating Trek SDK integration.

Related Repos

Repo	Purpose
trek-go	Go SDK
trek-cli	CLI (trek command)
trek-spec	Conformance fixtures