v0.7.0

Architecture

Last updated


HakoRun's module layers and the components a request passes through.

System Overview


graph TB
    Main[cmd/api entry] --> Checker[checker dependency check]
    Main --> DB[database init]
    Main --> Slice[sandbox.NewSlice]
    Main --> Router[internal router]
    Client[Client] --> Router
    Router --> Handler[handler Upload / Run / RunNow]
    Handler --> Store[(ToriiDB / Redis)]
    Handler --> Sandbox[sandbox.SandboxCommand]
    Sandbox --> Wrapper[internal/resource wrapper]
    Wrapper --> Handler
    Handler --> Client
  1. graph TB
  2. Main[cmd/api entry] --> Checker[checker dependency check]
  3. Main --> DB[database init]
  4. Main --> Slice[sandbox.NewSlice]
  5. Main --> Router[internal router]
  6. Client[Client] --> Router
  7. Router --> Handler[handler Upload / Run / RunNow]
  8. Handler --> Store[(ToriiDB / Redis)]
  9. Handler --> Sandbox[sandbox.SandboxCommand]
  10. Sandbox --> Wrapper[internal/resource wrapper]
  11. Wrapper --> Handler
  12. Handler --> Client

Layers


LayerPathResponsibility
Entrycmd/api/main.goRuns the dependency check, storage init, slice setup, and HTTP server in order; handles signals with a 5-second shutdown
Routerinternal/router.goBuilds the Gin engine, registers /upload, /run/*targetPath, /run-now, and binds HTTP_PORT
Handlerinternal/handler/Validates requests, loads scripts, picks one-shot or SSE execution, tags the response type
Storageinternal/database/backend interface; a build tag selects ToriiDB or Redis
Sandboxinternal/sandbox/Builds systemd-run + bwrap or sandbox-exec commands per platform; writes hakorun.slice on Linux
Checkerinternal/checker/Detects and installs runtimes on Linux; a no-op on macOS
Wrapperinternal/resource/Each language reads {code, input} from stdin and runs the user code

Cross-cutting Principles


  • Platform differences split by Go build tags (_linux.go / _darwin.go), not runtime checks.
  • Storage backends split by build tags (!redis / redis) and implement the same backend interface.
  • User code always reaches the wrapper through stdin and never touches the filesystem.
  • Every run is a fresh child process; no warm processes or state carry over.

OpenFaaS, Fn Project, and fx package each function as a container; HakoRun builds no images and runs each call as a child process of the server inside Bubblewrap (Linux) or sandbox-exec (macOS). judge0 and dify-sandbox are sandboxed code execution services, and Orva is a self-hosted FaaS for Node.js and Python built on nsjail; HakoRun centers on functions stored under a path with timestamp versions, Python, JavaScript, and TypeScript runtimes, and optional SSE streaming of output.

Further Reading


中文