Checkpoint

server/README.md

@@ -0,0 +1,164 @@
+# Server Package
+
+This package contains the restructured HTTP server implementation for HAMView.
+
+## Structure
+
+```
+server/
+├── server.go              # Main server setup and configuration
+├── router.go              # Route configuration with nested routers
+├── handlers_radios.go     # Radio endpoint handlers
+├── handlers_meshcore.go   # MeshCore endpoint handlers
+├── error.go               # Error handling utilities
+└── server_test.go         # Test infrastructure and test cases
+```
+
+## Design Principles
+
+### Clean Separation of Concerns
+
+- **server.go**: Server initialization, configuration, and lifecycle management
+- **router.go**: Centralized route definition using Echo's Group feature for nested routing
+- **handlers_*.go**: Domain-specific handler functions grouped by feature
+- **error.go**: Consistent error handling across all endpoints
+
+### Nested Routers
+
+The routing structure uses Echo's Group feature to create a clean hierarchy:
+
+```
+/api/v1
+├── /radios
+│   ├── GET /          -> handleGetRadios
+│   └── GET /:protocol -> handleGetRadios
+└── /meshcore
+    ├── GET /                         -> handleGetMeshCore
+    ├── GET /groups                   -> handleGetMeshCoreGroups
+    ├── GET /packets                  -> handleGetMeshCorePackets
+    └── /nodes
+        ├── GET /                     -> handleGetMeshCoreNodes
+        └── GET /close-to/:publickey  -> handleGetMeshCoreNodesCloseTo
+```
+
+### Testing Infrastructure
+
+The test suite uses an in-memory SQLite3 database for fast, isolated unit tests:
+
+- **setupTestServer()**: Creates a test Echo instance with routes and in-memory DB
+- **teardownTestServer()**: Cleans up test resources
+- Test cases cover all endpoints with various query parameters
+- Benchmarks for performance testing
+- Example showing how to populate test data
+
+## Usage
+
+### Creating a Server
+
+```go
+import (
+    "github.com/sirupsen/logrus"
+    "git.maze.io/ham/hamview/server"
+)
+
+logger := logrus.New()
+
+serverConfig := &server.Config{
+    Listen: ":8073",
+}
+
+dbConfig := &server.DatabaseConfig{
+    Type: "postgres",
+    Conf: "host=localhost user=ham dbname=hamview",
+}
+
+srv, err := server.New(serverConfig, dbConfig, logger)
+if err != nil {
+    log.Fatal(err)
+}
+
+if err := srv.Run(); err != nil {
+    log.Fatal(err)
+}
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+go test -v ./server/
+
+# Run specific test
+go test -v ./server/ -run TestRadiosEndpoints
+
+# Run with coverage
+go test -v -cover ./server/
+
+# Run benchmarks
+go test -v -bench=. ./server/
+```
+
+### Adding New Endpoints
+
+1. **Add handler function** in the appropriate `handlers_*.go` file:
+   ```go
+   func (s *Server) handleNewEndpoint(c echo.Context) error {
+       // Implementation
+       return c.JSON(http.StatusOK, result)
+   }
+   ```
+
+2. **Register route** in `router.go`:
+   ```go
+   func setupSomethingRoutes(s *Server, api *echo.Group) {
+       group := api.Group("/something")
+       group.GET("/new", s.handleNewEndpoint)
+   }
+   ```
+
+3. **Add test** in `server_test.go`:
+   ```go
+   func TestNewEndpoint(t *testing.T) {
+       e, _ := setupTestServer(t)
+       defer teardownTestServer(t)
+
+       req := httptest.NewRequest(http.MethodGet, "/api/v1/something/new", nil)
+       rec := httptest.NewRecorder()
+
+       e.ServeHTTP(rec, req)
+
+       // Assertions
+   }
+   ```
+
+## Backward Compatibility
+
+The root `server.go` file maintains backward compatibility by re-exporting types and providing a compatibility wrapper for `NewServer()`. Existing code continues to work without changes.
+
+## Best Practices
+
+1. **Handler naming**: Use `handle` prefix (e.g., `handleGetRadios`)
+2. **Context parameter**: Use short name `c` for `echo.Context`
+3. **Error handling**: Always use `s.apiError()` for consistent error responses
+4. **Query parameters**: Use helper functions like `getQueryInt()` for parsing
+5. **Testing**: Write tests for both success and error cases
+6. **Documentation**: Add godoc comments for exported functions
+
+## Performance Considerations
+
+- Use in-memory SQLite for tests (fast and isolated)
+- Benchmark critical endpoints
+- Use Echo's built-in middleware for CORS, logging, etc.
+- Consider adding route-specific middleware for caching or rate limiting
+
+## Future Enhancements
+
+Potential improvements to consider:
+
+- [ ] Add middleware for authentication/authorization
+- [ ] Implement request validation using a schema library
+- [ ] Add structured logging with trace IDs
+- [ ] Implement health check and metrics endpoints
+- [ ] Add integration tests with a real PostgreSQL instance
+- [ ] Consider adding OpenAPI/Swagger documentation
+- [ ] Add graceful shutdown handling