How enclaverunner/api-server works
Project Type and Purpose
• This is a Go-based, OpenAPI-driven backend service (“API server”) for managing secure enclave resources.
• It generates both server stubs and client code from an OpenAPI spec (openapi.yml) and implements persistence via an internal ORM layer.
File Structure Analysis
• Top-level:
• main.go: application entry point
• api/: generated server interface (gen.go) + business logic implementations (impl.go, rbac.go, users.go)
• orm/: database abstraction (init, model definitions, auth, users, error handling)
• client/: generated Go client (client.gen.go)
• config/: runtime configuration loader
• openapi.yml + oapi-codegen-*.yml: OpenAPI spec + codegen configuration
• Dockerfile, docker-compose.test.yml: container and test orchestration
• .github/workflows: CI, image promotion, releases, OpenAPI sync
• The Makefile and tools.go orchestrate codegen, linting, testing, and build targets.
• Nix flake files indicate reproducible dev/test environments.
README Insights
• Very concise: “API server provides secure endpoints for managing enclave resources and operations.”
• Implies strict security, RBAC, user management.
Main Components
a. OpenAPI Spec & Codegen
• Input: openapi.yml
• Codegen tools: oapi-codegen (server + client)
• Outputs: api/gen.go (server interfaces), client/client.gen.go (client SDK)
b. API Layer (Handlers & RBAC)
• api/impl.go: concrete handler implementations
• api/rbac.go: access control rules
• api/users.go: user-related endpoints
c. ORM / Persistence
• orm/init.go: DB connection bootstrap
• orm/model.go: entity definitions
• orm/auth.go, orm/users.go: data access methods
d. Configuration & Startup
• config/config.go: reads env, files, flags
• main.go: wires config, DB, router, middleware, starts HTTP server
e. External Dependencies
• Relational database (e.g. Postgres)
• External services (if any) called by handlers
f. Dev/Ops Tooling (Auxiliary)
• Docker image build & Docker Compose for integration tests
• GitHub Actions workflows for CI/CD
• Nix flake for reproducible environment
Relationships & Data Flow
• Developers edit openapi.yml → run Makefile/tooling → regenerate API & client code
• main.go initializes config → connects to DB via orm/init.go → sets up HTTP router using generated API interfaces
• Incoming HTTP request → API handler (impl.go) → RBAC check (rbac.go) → ORM call (e.g. orm/users.go) → DB → return data → API layer serializes JSON → HTTP response
• Client code (client/client.gen.go) calls the same openapi-defined endpoints.
Architectural Patterns & Principles
• API-first design via OpenAPI
• Clear separation of concerns:
• Spec & codegen
• Handler layer (business logic + RBAC)
• Data access layer (ORM)
• Configuration & bootstrapping
• CI/CD pipelines enforce code generation, linting, tests, and release workflows.
Detailed Elements
• Spec & codegen workflow
• API interface vs implementation
• RBAC enforcement as middleware
• ORM’s role in persistence
• Configuration injection in main
• CI/CD (GitHub Actions) and containerization pipelines