feat: dockerize goscribe for homelab deployment

[fabienpiette]

Summary

Transform goscribe from a local CLI tool into a homelab-deployable HTTP service with Redis-backed async job queue. Adds a new server binary (cmd/server) while keeping the existing CLI untouched.

Why

Enable goscribe to be consumed by other homelab services via HTTP API. The async job queue allows long-running transcription tasks to be processed in the background with webhook notifications on completion.

How

• HTTP API layer using chi router with endpoints: POST /jobs, GET /jobs/{id}, GET /actions, GET /health
• Async queue using asynq + Redis for job processing
• Worker processor handles transcription and post-processing with the existing provider package
• Server modes: all (default), api (HTTP only), worker (queue consumer only)
• Docker multi-stage build with non-root user

Changes

• Add cmd/server - HTTP server with mode switching and graceful shutdown
• Add internal/api/handler.go - HTTP handlers for all endpoints
• Add internal/api/router.go - chi router configuration
• Add internal/worker/processor.go - asynq task processor
• Add internal/worker/tasks.go - task types and result structs
• Add Dockerfile - multi-stage build (golang:1.24-alpine → alpine:3.19)
• Add docker-compose.yml - goscribe + redis services with profiles for split-mode
• Add .env.example - environment variable documentation
• Modify pkg/config - add DefaultPostActions() for server use

Security Fixes (Post-Initial Review)

• SSRF protection: Validate webhook URLs against private IP ranges using custom http.Transport with DialContext validation
• DNS rebinding protection: Resolve DNS once and connect directly to validated IP, closing TOCTOU gap
• IPv4-mapped IPv6: Properly handle ::ffff:x.x.x.x addresses
• Graceful shutdown: Changed log.Fatalf to log.Printf to ensure shutdown code is reached
• HTTP server timeouts: Added ReadHeaderTimeout, WriteTimeout, IdleTimeout for slow-loris protection
• REDIS_URL parsing: Use url.Parse for proper host extraction

Split-Mode Deployment

• Default: docker compose up → starts goscribe (MODE=all) + redis
• Split: docker compose --profile split up → starts goscribe-api + goscribe-worker + redis

Testing

• All existing tests pass
• Docker image builds successfully (~147MB)
• Image runs as non-root user (goscribe)
• golangci-lint passes

Checklist

• Code follows project style guidelines
• Self-reviewed own code
• No new warnings introduced
• Tests pass locally
• Docker build verified

Impact

• Breaking changes: None
• Database migrations: None

[fabienpiette]

Code review

Found 6 issues:

1. SSRF via unvalidated webhook_url — webhook_url from the form is passed directly to http.Post() in the worker with no URL validation. An attacker can submit a job with a webhook pointing to internal services (e.g., http://169.254.169.254/latest/meta-data/, Redis on localhost:6379, or internal Kubernetes endpoints) and the worker will faithfully POST job results there.

goscribe/internal/api/handler.go

Lines 60 to 62 in f8df8ba

	provider := r.FormValue("provider")
	webhookURL := r.FormValue("webhook_url")

goscribe/internal/worker/processor.go

Lines 202 to 208 in f8df8ba

	}
	resp, err := http.Post(url, "application/json", bytes.NewReader(b))
	if err != nil {
	return
	}
	resp.Body.Close()
	}

2. log.Fatalf bypasses graceful shutdown — when either server goroutine sends to errCh, log.Fatalf calls os.Exit(1) immediately. The shutdown block below the select (which drains HTTP connections and stops the asynq worker) is never reached, abandoning in-flight jobs and open connections.

goscribe/cmd/server/main.go

Lines 86 to 103 in f8df8ba

	select {
	case err := <-errCh:
	log.Fatalf("fatal error: %v", err)
	case sig := <-quit:
	log.Printf("received %v, shutting down (timeout=%s)...", sig, cfg.shutdownTimeout)
	}
	shutdownCtx, cancel := context.WithTimeout(context.Background(), cfg.shutdownTimeout)
	defer cancel()
	if httpSrv != nil {
	if err := httpSrv.Shutdown(shutdownCtx); err != nil {
	log.Printf("HTTP shutdown error: %v", err)
	}
	}
	if asynqSrv != nil {
	asynqSrv.Shutdown()

3. Split-mode deployment silently broken — when MODE=api and MODE=worker run in separate containers, uploaded audio files are saved to the API container's local filesystem. The worker receives only the path string and cannot access the file; no shared volume is defined in docker-compose.yml. Every transcription job will fail with a file-not-found error in split mode.

goscribe/docker-compose.yml

Lines 1 to 27 in f8df8ba

	services:
	goscribe:
	build: .
	ports:
	- "8080:8080"
	env_file:
	- .env
	environment:
	- REDIS_URL=redis://redis:6379
	depends_on:
	redis:
	condition: service_healthy
	restart: unless-stopped
	redis:
	image: redis:7-alpine
	volumes:
	- redis_data:/data
	command: redis-server --appendonly yes
	healthcheck:
	test: ["CMD", "redis-cli", "ping"]
	interval: 5s
	timeout: 3s
	retries: 5
	restart: unless-stopped
	volumes:

4. REDIS_URL parsing silently breaks for non-trivial URLs — strings.TrimPrefix(redisURL, "redis://") does not match rediss:// (TLS), leaving the full URL as the address. It also passes database numbers and credentials fragments as part of the host string for URLs like redis://user:pass@host:6379/1. Both asynq and go-redis expect a bare host:port. Use url.Parse instead.

goscribe/cmd/server/main.go

Lines 124 to 127 in f8df8ba

	func loadConfig() serverConfig {
	redisURL := getenv("REDIS_URL", "redis://redis:6379")
	redisAddr := strings.TrimPrefix(redisURL, "redis://")

5. fireWebhook uses http.DefaultClient with no timeout — http.Post() uses the package-level default client, which has no timeout. If the webhook endpoint is slow or unreachable, the worker goroutine blocks indefinitely. With the default concurrency of 5 workers, 5 concurrent stalled webhooks exhaust the pool.

goscribe/internal/worker/processor.go

Lines 198 to 208 in f8df8ba

	func (p *Processor) fireWebhook(url string, result JobResult) {
	b, err := json.Marshal(result)
	if err != nil {
	return
	}
	resp, err := http.Post(url, "application/json", bytes.NewReader(b))
	if err != nil {
	return
	}
	resp.Body.Close()
	}

6. http.Server has no read/write timeouts — the server is created without ReadHeaderTimeout, ReadTimeout, or WriteTimeout, making it vulnerable to slow-loris connection exhaustion. Standard practice for any publicly accessible Go HTTP server is to set at minimum ReadHeaderTimeout.

goscribe/cmd/server/main.go

Lines 174 to 181 in f8df8ba

	DefaultProvider: cfg.provider,
	})
	return &http.Server{
	Addr: ":" + cfg.port,
	Handler: api.NewRouter(h),
	}
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[fabienpiette]

/gemini review

[gemini-code-assist]

Code Review

The pull request successfully dockerizes goscribe, introducing an HTTP REST API, a Redis-backed async job queue, and a worker processor. The Docker setup uses a multi-stage build, and docker-compose.yml is provided for easy deployment. New Makefile targets simplify Docker operations. Overall, the changes are well-structured and introduce significant new functionality. However, there are some areas for improvement regarding error handling and security hardening, particularly around configuration parsing and webhook validation.