monorepo/cloud/maplefile-backend/internal/interface/http/README.md

MapleFile HTTP Server

Standalone HTTP server for MapleFile backend - completely independent with no Manifold orchestration.

Architecture

• Standard Library: Uses net/http with Go 1.22+ routing patterns
• No Orchestration: Direct route registration (no AsRoute() wrappers)
• Middleware Stack: Applied globally with per-route authentication
• Lifecycle Management: Integrated with Uber FX for graceful shutdown

Server Configuration

Configured via environment variables in .env:

SERVER_HOST=0.0.0.0
SERVER_PORT=8000
SERVER_READ_TIMEOUT=30s
SERVER_WRITE_TIMEOUT=30s
SERVER_IDLE_TIMEOUT=60s
SERVER_SHUTDOWN_TIMEOUT=10s

Middleware Stack

Applied in this order (outermost to innermost):

1. Recovery - Catches panics and returns 500
2. Logging - Logs all requests with duration
3. CORS - Handles cross-origin requests
4. Authentication (per-route) - JWT validation for protected routes

Route Structure

Public Routes

• GET /health - Health check
• GET /version - Version info
• POST /api/v1/auth/register - Registration
• POST /api/v1/auth/login - Login

Protected Routes

All /api/v1/* routes (except auth) require JWT authentication via:

Authorization: Bearer <jwt_token>

Key protected endpoints include:

• GET/PUT/DELETE /api/v1/me - User profile management
• POST/GET/PUT/DELETE /api/v1/collections/* - Collection CRUD
• POST/GET/PUT/DELETE /api/v1/file/* - File operations
• POST /api/v1/invites/send-email - Send invitation to non-registered user

See routes.go for complete endpoint list.

Handler Registration

Routes are registered in server.go -> registerRoutes():

// Public route
s.mux.HandleFunc("GET /health", s.healthCheckHandler)

// Protected route
s.mux.HandleFunc("POST /api/v1/collections",
    s.middleware.Attach(s.handlers.CreateCollection))

Starting the Server

The server is started automatically by Uber FX:

fx.New(
    fx.Provide(http.NewServer),  // Creates and starts server
    // ... other providers
)

Lifecycle hooks handle:

• OnStart: Starts HTTP listener in goroutine
• OnStop: Graceful shutdown with timeout

Response Format

All JSON responses follow this structure:

Success:

{
  "data": { ... },
  "message": "Success"
}

Error:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Health Checks

# Basic health check
curl http://localhost:8000/health

# Version check
curl http://localhost:8000/version

Development

Build and run:

task build
./maplefile-backend daemon

The server will start on http://localhost:8000 by default.