How zhaofengli/attic works
Project Type & Purpose
• Attic is a self-hostable Nix Binary Cache server. Its primary function is to serve as a binary cache backed by an S3-compatible storage provider. Core goals include multi-tenancy, global deduplication, managed signing, and garbage collection.
• The project is written in Rust and is organized into multiple Cargo packages (attic, client, server, token) that collaboratively implement the caching server, the CLI client, token/authentication support, and shared libraries.
Main Architectural Components
• Attic Core Library ("attic" directory):
• Contains the core logic including API definitions, chunking, hashing, signing, Nix store bindings, and utility functionality.
• Modules are further split (e.g., src/api, src/chunking, src/error, src/nix_store) so that the underlying binary cache operations, deduplication, and signing logic are encapsulated here.
• Server ("server" directory):
• Implements the actual Nix binary cache server binary. Includes API endpoints (with multiple API versions under src/api/v1) handling operations like uploading paths, fetching missing paths, and binary cache management.
• Integrates with a database (see the database directory with migration files and entities) which maps tenants to cached content and maintains metadata.
• Manages HTTP access and other middleware components.
• Client ("client" directory):
• Provides a command-line tool for interacting with the server, handling tasks such as login, pushing binaries, cache commands, and configuration.
• Acts as the user-facing interface that triggers API requests to the server.
• Token ("token" directory):
• Contains logic for handling token operations, possibly for access control or managed signing, which is essential for securing the interactions.
• Additional Components:
• CI/Integration Testing & Documentation:
• .ci, GitHub workflows, integration-tests directories indicate a continuous integration pipeline.
• The book directory hosts user guides and reference materials, explaining how to deploy and use Attic.
• Build & Deployment Scripts:
• Files like shell.nix, flake.nix, and various Nix configurations suggest a reproducible build and deployment environment, including support for serverless platforms.
Relationships and Data Flow
• Client-to-Server Interaction:
• Server Internals:
• Inside the Server component, delineate the API handling (shown as separate modules such as API v1 endpoints).
• A connection from the Server to the shared Attic Core libraries for operations such as deduplication (via chunking & hashing) and for invoking the signing service.
• Database and Storage Interaction:
• A Database component which represents the persistent data store. Represent the server’s interactions with the database (for migrations, cache entity management, etc.).
• Token Handling:
• A Token Service/Module which may be used both by the Server (for signing or authentication) and by the Client if session tokens or API keys are managed.
• CI/CD Pipeline:
Expected Architectural Patterns
• Modularity: The decomposition into multiple Cargo packages (core library, server, client, token) clearly suggests adherence to modular design.
• API-first and Layered Architecture: The separation of API modules, middleware, storage, and helper libraries (e.g., for chunking, hashing) indicates clean layering.
• Self-Containment & Extensibility: Having separate directories for tests, docs, and integrations illustrates a maintainable and extensible system.
Final Touches
• Even if the components are highly interdependent (like the interactions between the core logic and different binaries), separating them clearly helps in understanding the architecture.
• Avoid over-cluttering; group related modules with clear boundaries (for example, all components under “Attic Core” can be grouped together, while “Client” remains distinct).