api

type AuthConfig struct {
	Handler      *auth.Handler
	SessionStore auth.Store

	// Cipher decrypts the GitHub access token stored on a session. Handlers
	// that act as the requesting user (e.g. runtime repo onboarding verifying
	// the user's access to a repo) need it to recover the token from
	// SessionFromContext. It is the same cipher the OAuth handler sealed with.
	Cipher *auth.Cipher
}

type RateLimitConfig struct {
	RequestsPerSecond float64
	Burst             int
}

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

type ServerConfig struct {
	// BindAddr is the host/IP to listen on. Empty means "all interfaces".
	// apps/server picks a safe default (127.0.0.1) and binds 0.0.0.0 when
	// STACKIT_ENV=production.
	BindAddr    string
	Port        int
	CORSOrigins []string

	// AllowLoopbackOrigins accepts any loopback browser origin (localhost /
	// 127.0.0.1 / [::1] on any port) in addition to CORSOrigins. apps/server
	// sets it only on a loopback bind so local dev web servers — whose port is
	// environment-assigned — work without a fixed allowlist entry. An exposed
	// server leaves it false and keeps the strict explicit allowlist.
	AllowLoopbackOrigins bool

	APIPrefixes []string
	StaticFS    fs.FS
	Registry    *registry.Registry

	// SSELimits bounds concurrent Server-Sent Events connections. Zero
	// fields take the package defaults, which are generous enough for normal
	// use but cap the blast radius of a public deployment.
	SSELimits handlers.SSELimits

	// RateLimit configures the per-IP request rate limiter applied to the
	// API. Zero fields take the defaults; a negative RequestsPerSecond
	// disables limiting.
	RateLimit RateLimitConfig

	// BranchDiffConcurrency caps how many branch-diff requests run their git
	// subprocesses at once. Zero takes the handler default.
	BranchDiffConcurrency int

	// SingleRepo marks single-repo mode (the local -cwd/discovery shortcut, not
	// the DB-backed multi-tenant model). It is surfaced via /api/v1/config so
	// the web client skips the repo picker and opens the sole repo directly.
	SingleRepo bool

	// ReadOnly puts the server into a public read-only posture: the
	// mutating submit route is replaced with a handler that refuses with
	// 405 so writes are impossible by construction, not just by policy.
	// This is the safety floor for exposing a repo publicly — a read-only
	// server cannot push branches or touch GitHub no matter who calls it.
	ReadOnly bool

	// Auth bundles the OAuth handler, session store, and surrounding state
	// needed to gate /api/* routes behind GitHub login. When nil the server
	// runs without authentication; that mode is only safe on a private
	// network (localhost dev, tunneled access). apps/server refuses to
	// start unauthenticated when it binds a non-loopback interface unless
	// -read-only is set.
	Auth *AuthConfig

	// RepoStore is the persistence backend for repo configuration. It is set
	// only when the server runs in DB-backed mode (-database-url). Runtime
	// repo onboarding persists new repos here so they survive a restart; when
	// nil, onboarding is unavailable and the registry is fixed at boot.
	RepoStore *store.Store

	// ReposRoot is the absolute base directory under which onboarded repos are
	// checked out (<ReposRoot>/<owner>/<name>). Required for runtime
	// onboarding; when empty, onboarding is refused.
	ReposRoot string

	// RepoSyncTokens mints GitHub App installation tokens for git operations on
	// managed repos. It authenticates onboarding clones and background syncs.
	// Nil when no GitHub App is configured, in which case onboarding is refused
	// and the sync loop can only fetch public repos.
	RepoSyncTokens *githubpkg.AppTokenProvider

	// SyncInterval, when > 0, enables the background sync loop: every interval
	// each managed repo is mirror-fetched from its remote so the served state
	// stays current without a local actor. Zero disables it. Even with the loop
	// off, the syncer still backs on-demand refreshes (webhook receiver).
	SyncInterval time.Duration

	// GitHubWebhookSecret is the shared secret GitHub signs webhook deliveries
	// with. When set, POST /api/v1/webhooks/github accepts verified push events
	// and refreshes the matching managed repo immediately (the interval loop
	// stays as a backstop). Empty disables the endpoint (it 404s), which is the
	// correct posture for local/dev servers GitHub can't reach.
	GitHubWebhookSecret string

	// WebhookDebounce is the quiet window a repo's webhook triggers wait out
	// before a fetch runs, so a stack submit's burst of pushes collapses into a
	// single refresh. Negative uses the package default; zero dispatches
	// immediately.
	WebhookDebounce time.Duration
}