Implement mcdoc v0.1.0: public documentation server
Single-binary Go server that fetches markdown from Gitea (mc org), renders to HTML with goldmark (GFM, chroma syntax highlighting, heading anchors), and serves a navigable read-only documentation site. Features: - Boot fetch with retry, webhook refresh, 15-minute poll fallback - In-memory cache with atomic per-repo swap - chi router with htmx partial responses for SPA-like navigation - HMAC-SHA256 webhook validation - Responsive CSS, TOC generation, priority doc ordering - $PORT env var support for MCP agent port assignment 33 tests across config, cache, render, and server packages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
164
internal/config/config.go
Normal file
164
internal/config/config.go
Normal file
@@ -0,0 +1,164 @@
|
||||
package config
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"reflect"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/pelletier/go-toml/v2"
|
||||
)
|
||||
|
||||
type Config struct {
|
||||
Server ServerConfig `toml:"server"`
|
||||
Gitea GiteaConfig `toml:"gitea"`
|
||||
Log LogConfig `toml:"log"`
|
||||
}
|
||||
|
||||
type ServerConfig struct {
|
||||
ListenAddr string `toml:"listen_addr"`
|
||||
}
|
||||
|
||||
type GiteaConfig struct {
|
||||
URL string `toml:"url"`
|
||||
Org string `toml:"org"`
|
||||
WebhookSecret string `toml:"webhook_secret"`
|
||||
PollInterval Duration `toml:"poll_interval"`
|
||||
FetchTimeout Duration `toml:"fetch_timeout"`
|
||||
MaxConcurrency int `toml:"max_concurrency"`
|
||||
ExcludePaths ExcludePaths `toml:"exclude_paths"`
|
||||
ExcludeRepos ExcludeRepos `toml:"exclude_repos"`
|
||||
}
|
||||
|
||||
type ExcludePaths struct {
|
||||
Patterns []string `toml:"patterns"`
|
||||
}
|
||||
|
||||
type ExcludeRepos struct {
|
||||
Names []string `toml:"names"`
|
||||
}
|
||||
|
||||
type LogConfig struct {
|
||||
Level string `toml:"level"`
|
||||
}
|
||||
|
||||
// Duration wraps time.Duration for TOML string parsing.
|
||||
type Duration struct {
|
||||
time.Duration
|
||||
}
|
||||
|
||||
func (d *Duration) UnmarshalText(text []byte) error {
|
||||
var err error
|
||||
d.Duration, err = time.ParseDuration(string(text))
|
||||
return err
|
||||
}
|
||||
|
||||
func (d Duration) MarshalText() ([]byte, error) {
|
||||
return []byte(d.String()), nil
|
||||
}
|
||||
|
||||
func Load(path string) (*Config, error) {
|
||||
data, err := os.ReadFile(path) // #nosec G304 -- config path is operator-controlled
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read config: %w", err)
|
||||
}
|
||||
|
||||
cfg := &Config{
|
||||
Server: ServerConfig{
|
||||
ListenAddr: ":8080",
|
||||
},
|
||||
Gitea: GiteaConfig{
|
||||
URL: "https://git.wntrmute.dev",
|
||||
Org: "mc",
|
||||
PollInterval: Duration{15 * time.Minute},
|
||||
FetchTimeout: Duration{30 * time.Second},
|
||||
MaxConcurrency: 4,
|
||||
ExcludePaths: ExcludePaths{
|
||||
Patterns: []string{"vendor/", ".claude/", "node_modules/", ".junie/"},
|
||||
},
|
||||
},
|
||||
Log: LogConfig{
|
||||
Level: "info",
|
||||
},
|
||||
}
|
||||
|
||||
if err := toml.Unmarshal(data, cfg); err != nil {
|
||||
return nil, fmt.Errorf("parse config: %w", err)
|
||||
}
|
||||
|
||||
applyEnvOverrides(cfg)
|
||||
|
||||
if err := cfg.validate(); err != nil {
|
||||
return nil, fmt.Errorf("validate config: %w", err)
|
||||
}
|
||||
|
||||
return cfg, nil
|
||||
}
|
||||
|
||||
func (c *Config) validate() error {
|
||||
if c.Server.ListenAddr == "" {
|
||||
return fmt.Errorf("server.listen_addr is required")
|
||||
}
|
||||
if c.Gitea.URL == "" {
|
||||
return fmt.Errorf("gitea.url is required")
|
||||
}
|
||||
if c.Gitea.Org == "" {
|
||||
return fmt.Errorf("gitea.org is required")
|
||||
}
|
||||
if c.Gitea.MaxConcurrency < 1 {
|
||||
return fmt.Errorf("gitea.max_concurrency must be >= 1")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// applyEnvOverrides checks for MCDOC_* environment variables and applies
|
||||
// them to the config. Also checks $PORT for MCP agent port assignment.
|
||||
func applyEnvOverrides(cfg *Config) {
|
||||
if port := os.Getenv("PORT"); port != "" {
|
||||
cfg.Server.ListenAddr = ":" + port
|
||||
}
|
||||
|
||||
applyEnvToStruct("MCDOC", reflect.ValueOf(cfg).Elem())
|
||||
}
|
||||
|
||||
func applyEnvToStruct(prefix string, v reflect.Value) {
|
||||
t := v.Type()
|
||||
for i := range t.NumField() {
|
||||
field := t.Field(i)
|
||||
fv := v.Field(i)
|
||||
|
||||
tag := field.Tag.Get("toml")
|
||||
if tag == "" || tag == "-" {
|
||||
continue
|
||||
}
|
||||
|
||||
envKey := prefix + "_" + strings.ToUpper(tag)
|
||||
|
||||
if fv.Kind() == reflect.Struct && field.Type != reflect.TypeOf(Duration{}) {
|
||||
applyEnvToStruct(envKey, fv)
|
||||
continue
|
||||
}
|
||||
|
||||
envVal := os.Getenv(envKey)
|
||||
if envVal == "" {
|
||||
continue
|
||||
}
|
||||
|
||||
switch fv.Kind() {
|
||||
case reflect.String:
|
||||
fv.SetString(envVal)
|
||||
case reflect.Int:
|
||||
var n int
|
||||
if _, err := fmt.Sscanf(envVal, "%d", &n); err == nil {
|
||||
fv.SetInt(int64(n))
|
||||
}
|
||||
}
|
||||
|
||||
if field.Type == reflect.TypeOf(Duration{}) {
|
||||
if d, err := time.ParseDuration(envVal); err == nil {
|
||||
fv.Set(reflect.ValueOf(Duration{d}))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
154
internal/config/config_test.go
Normal file
154
internal/config/config_test.go
Normal file
@@ -0,0 +1,154 @@
|
||||
package config
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestLoadValidConfig(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
path := filepath.Join(dir, "mcdoc.toml")
|
||||
|
||||
content := `
|
||||
[server]
|
||||
listen_addr = ":9090"
|
||||
|
||||
[gitea]
|
||||
url = "https://git.example.com"
|
||||
org = "myorg"
|
||||
webhook_secret = "secret123"
|
||||
poll_interval = "5m"
|
||||
fetch_timeout = "10s"
|
||||
max_concurrency = 2
|
||||
|
||||
[gitea.exclude_paths]
|
||||
patterns = ["vendor/"]
|
||||
|
||||
[gitea.exclude_repos]
|
||||
names = ["ignore-me"]
|
||||
|
||||
[log]
|
||||
level = "debug"
|
||||
`
|
||||
if err := os.WriteFile(path, []byte(content), 0600); err != nil {
|
||||
t.Fatalf("write config: %v", err)
|
||||
}
|
||||
|
||||
cfg, err := Load(path)
|
||||
if err != nil {
|
||||
t.Fatalf("load: %v", err)
|
||||
}
|
||||
|
||||
if cfg.Server.ListenAddr != ":9090" {
|
||||
t.Fatalf("listen_addr = %q, want :9090", cfg.Server.ListenAddr)
|
||||
}
|
||||
if cfg.Gitea.URL != "https://git.example.com" {
|
||||
t.Fatalf("gitea.url = %q", cfg.Gitea.URL)
|
||||
}
|
||||
if cfg.Gitea.Org != "myorg" {
|
||||
t.Fatalf("gitea.org = %q", cfg.Gitea.Org)
|
||||
}
|
||||
if cfg.Gitea.PollInterval.Duration != 5*time.Minute {
|
||||
t.Fatalf("poll_interval = %v", cfg.Gitea.PollInterval.Duration)
|
||||
}
|
||||
if cfg.Gitea.FetchTimeout.Duration != 10*time.Second {
|
||||
t.Fatalf("fetch_timeout = %v", cfg.Gitea.FetchTimeout.Duration)
|
||||
}
|
||||
if cfg.Gitea.MaxConcurrency != 2 {
|
||||
t.Fatalf("max_concurrency = %d", cfg.Gitea.MaxConcurrency)
|
||||
}
|
||||
if len(cfg.Gitea.ExcludePaths.Patterns) != 1 {
|
||||
t.Fatalf("exclude_paths = %v", cfg.Gitea.ExcludePaths.Patterns)
|
||||
}
|
||||
if len(cfg.Gitea.ExcludeRepos.Names) != 1 {
|
||||
t.Fatalf("exclude_repos = %v", cfg.Gitea.ExcludeRepos.Names)
|
||||
}
|
||||
if cfg.Log.Level != "debug" {
|
||||
t.Fatalf("log.level = %q", cfg.Log.Level)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadDefaults(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
path := filepath.Join(dir, "mcdoc.toml")
|
||||
|
||||
// Minimal config — everything should get defaults
|
||||
if err := os.WriteFile(path, []byte(""), 0600); err != nil {
|
||||
t.Fatalf("write config: %v", err)
|
||||
}
|
||||
|
||||
cfg, err := Load(path)
|
||||
if err != nil {
|
||||
t.Fatalf("load: %v", err)
|
||||
}
|
||||
|
||||
if cfg.Server.ListenAddr != ":8080" {
|
||||
t.Fatalf("default listen_addr = %q, want :8080", cfg.Server.ListenAddr)
|
||||
}
|
||||
if cfg.Gitea.URL != "https://git.wntrmute.dev" {
|
||||
t.Fatalf("default gitea.url = %q", cfg.Gitea.URL)
|
||||
}
|
||||
if cfg.Gitea.PollInterval.Duration != 15*time.Minute {
|
||||
t.Fatalf("default poll_interval = %v", cfg.Gitea.PollInterval.Duration)
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadMissingFile(t *testing.T) {
|
||||
_, err := Load("/nonexistent/mcdoc.toml")
|
||||
if err == nil {
|
||||
t.Fatal("expected error for missing file")
|
||||
}
|
||||
}
|
||||
|
||||
func TestPortEnvOverride(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
path := filepath.Join(dir, "mcdoc.toml")
|
||||
if err := os.WriteFile(path, []byte(""), 0600); err != nil {
|
||||
t.Fatalf("write config: %v", err)
|
||||
}
|
||||
|
||||
t.Setenv("PORT", "12345")
|
||||
cfg, err := Load(path)
|
||||
if err != nil {
|
||||
t.Fatalf("load: %v", err)
|
||||
}
|
||||
if cfg.Server.ListenAddr != ":12345" {
|
||||
t.Fatalf("PORT override: got %q, want :12345", cfg.Server.ListenAddr)
|
||||
}
|
||||
}
|
||||
|
||||
func TestEnvOverride(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
path := filepath.Join(dir, "mcdoc.toml")
|
||||
if err := os.WriteFile(path, []byte(""), 0600); err != nil {
|
||||
t.Fatalf("write config: %v", err)
|
||||
}
|
||||
|
||||
t.Setenv("MCDOC_GITEA_ORG", "custom-org")
|
||||
cfg, err := Load(path)
|
||||
if err != nil {
|
||||
t.Fatalf("load: %v", err)
|
||||
}
|
||||
if cfg.Gitea.Org != "custom-org" {
|
||||
t.Fatalf("env override: got %q, want custom-org", cfg.Gitea.Org)
|
||||
}
|
||||
}
|
||||
|
||||
func TestValidationFailsOnEmptyURL(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
path := filepath.Join(dir, "mcdoc.toml")
|
||||
content := `
|
||||
[gitea]
|
||||
url = ""
|
||||
`
|
||||
if err := os.WriteFile(path, []byte(content), 0600); err != nil {
|
||||
t.Fatalf("write config: %v", err)
|
||||
}
|
||||
|
||||
_, err := Load(path)
|
||||
if err == nil {
|
||||
t.Fatal("expected validation error for empty gitea.url")
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user