mcdsl/PROGRESS.md

MCDSL Progress

Current State

Phases 0–9 complete. All nine packages are implemented and tested (87 tests). Ready for first-adopter migration (Phase 10).

Completed

Phase 0: Project Setup (2026-03-25)

• Go module, Makefile, .golangci.yaml (with exported rule), .gitignore

Phase 1: db — SQLite Foundation (2026-03-25)

• Open (WAL, FK, busy timeout, 0600, parent dirs), Migration type, Migrate (sequential, transactional, idempotent), SchemaVersion, Snapshot (VACUUM INTO)
• 11 tests

Phase 2: auth — MCIAS Token Validation (2026-03-25)

• Config, TokenInfo, Authenticator with Login/ValidateToken/Logout
• 30s SHA-256 cache, lazy eviction, RWMutex, context helpers
• 14 tests

Phase 3: config — TOML Configuration (2026-03-25)

• Base type, ServerConfig with Duration wrapper, Load[T] generic loader
• Env overrides via reflection, defaults, Validator interface
• 16 tests

Phase 4: httpserver — HTTP Server (2026-03-25)

• Server with chi + TLS 1.3, ListenAndServeTLS, Shutdown
• LoggingMiddleware, StatusWriter, WriteJSON, WriteError
• 8 tests

Phase 5: csrf — CSRF Protection (2026-03-25)

• HMAC-SHA256 double-submit cookies, Middleware, SetToken, TemplateFunc
• 10 tests

Phase 6: web — Session and Templates (2026-03-25)

• SetSessionCookie/ClearSessionCookie/GetSessionToken (HttpOnly, Secure, SameSite=Strict), RequireAuth middleware, RenderTemplate
• 9 tests

Phase 7: grpcserver — gRPC Server (2026-03-25)

• MethodMap (Public, AuthRequired, AdminRequired), default deny for unmapped
• Auth interceptor, logging interceptor, TLS 1.3 optional
• 10 tests

Phase 8: health — Health Checks (2026-03-25)

• REST Handler(db) — 200 ok / 503 unhealthy
• RegisterGRPC — grpc.health.v1.Health
• 4 tests

Phase 9: archive — Service Directory Snapshots (2026-03-25)

• Snapshot: tar.zst with VACUUM INTO db injection, exclude .db/.db-wal/ *.db-shm/backups/, custom exclude patterns, streaming output
• Restore: extract tar.zst to dest dir, path traversal protection
• 5 tests: full roundtrip with db integrity, without db, exclude live db, custom excludes, dest dir creation

Summary

Package	Tests	Key Exports
db	11	Open, Migration, Migrate, SchemaVersion, Snapshot
auth	14	Config, TokenInfo, Authenticator, context helpers
config	16	Base, ServerConfig, Duration, Load[T], Validator
httpserver	8	Server, LoggingMiddleware, WriteJSON, WriteError
csrf	10	Protect, Middleware, SetToken, TemplateFunc
web	9	SetSessionCookie, RequireAuth, RenderTemplate
grpcserver	10	MethodMap, Server (default deny), TokenInfoFromContext
health	4	Handler, RegisterGRPC
archive	5	Snapshot, Restore
Total	87

Next Steps

Phase 10: First Adopter — mcat (2026-03-25)

mcat migrated to use mcdsl. The following internal packages were removed and replaced:

Removed	Replaced by
internal/auth/ (auth.go, auth_test.go)	mcdsl/auth
internal/config/ (config.go, config_test.go)	mcdsl/config
internal/webserver/csrf.go	mcdsl/csrf

Remaining mcat-specific code:

• cmd/mcat/ — CLI wiring, mcatConfig type (embeds config.Base)
• internal/webserver/server.go — routes, handlers (using mcdsl/auth, mcdsl/csrf, mcdsl/web, mcdsl/httpserver)
• web/ — templates and static assets (unchanged)

Dependencies removed:

• git.wntrmute.dev/kyle/mcias/clients/go (mcdsl/auth handles MCIAS directly)
• github.com/pelletier/go-toml/v2 (now indirect via mcdsl/config)

Dependencies added:

• git.wntrmute.dev/kyle/mcdsl (local replace directive)

Result: vet clean, lint 0 issues, builds successfully.

Phase 11a: mc-proxy Migration (2026-03-25)

mc-proxy migrated db and config to mcdsl. Different pattern from mcat because mc-proxy doesn't embed config.Base (no [server] or [mcias] sections).

Changed	How
internal/db/db.go Open	Delegates to mcdsl/db.Open
internal/db/migrations.go	Function-based migrations → mcdsl/db.Migration SQL strings
internal/db/snapshot.go	Delegates to mcdsl/db.Snapshot
internal/config/config.go Duration	Type alias for mcdsl/config.Duration
internal/config/config.go Load	Uses mcdsl/config.Load[T] + Validator interface

Key design decisions:

• Store wrapper kept (has CRUD methods specific to mc-proxy)
• type Duration = mcdslconfig.Duration alias so all existing code referencing config.Duration continues to work unchanged
• mc-proxy's complex validation stays as a Validate() method
• Manual env overrides kept for int64 rate_limit (reflection can't handle)

Dependencies removed as direct:

• modernc.org/sqlite (now indirect via mcdsl)
• github.com/pelletier/go-toml/v2 (now indirect via mcdsl)

Behavioral change: invalid duration env overrides are now silently ignored (test updated to match).

Result: all tests pass, builds clean. Net -129 lines.

Phase 11b: mcr Migration (2026-03-25)

MCR migrated db, auth, and config to mcdsl. Exercises the full stack.

Changed	How
internal/db/db.go Open	Delegates to mcdsl/db.Open
internal/db/migrate.go	SQL strings → mcdsl/db.Migration, delegate to mcdsl/db.Migrate
internal/db/migrate.go SchemaVersion	Delegates to mcdsl/db.SchemaVersion
internal/auth/	Thin shim wrapping mcdsl/auth.Authenticator; keeps Claims type with AccountType for policy engine compatibility
internal/auth/cache.go	Deleted (caching handled by mcdsl/auth)
internal/config/config.go	Embeds mcdsl/config.Base; Storage and Web remain MCR-specific; uses mcdsl/config.Load[T] + Validator

Auth shim approach: MCR's policy engine depends on Claims.AccountType which mcdsl's TokenInfo doesn't carry. Rather than changing every consumer, internal/auth wraps mcdsl/auth.Authenticator and adapts results to the MCR Claims type. All server/grpcserver/webserver code is unchanged.

Behavioral changes:

• WriteTimeout now defaults to 30s (was 0/disabled)
• Auth cache expiry test removed (caching tested in mcdsl)

Result: all tests pass, builds clean. Net -464 lines.

Next Steps

• Phase 11c: metacrypt migration
• Phase 11d: mcias migration