122 lines
2.6 KiB
Markdown
122 lines
2.6 KiB
Markdown
# 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`:
|
|
|
|
```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()`:
|
|
|
|
```go
|
|
// 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:
|
|
|
|
```go
|
|
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:**
|
|
```json
|
|
{
|
|
"data": { ... },
|
|
"message": "Success"
|
|
}
|
|
```
|
|
|
|
**Error:**
|
|
```json
|
|
{
|
|
"error": "Error message",
|
|
"code": "ERROR_CODE"
|
|
}
|
|
```
|
|
|
|
## Health Checks
|
|
|
|
```bash
|
|
# Basic health check
|
|
curl http://localhost:8000/health
|
|
|
|
# Version check
|
|
curl http://localhost:8000/version
|
|
```
|
|
|
|
## Development
|
|
|
|
Build and run:
|
|
```bash
|
|
task build
|
|
./maplefile-backend daemon
|
|
```
|
|
|
|
The server will start on `http://localhost:8000` by default.
|