How seqeralabs/wave works
Main Components
a. API / Controller Layer: Representing REST endpoints that include endpoints like POST /container-token. The controllers (e.g., BuildController, ContainerController, MetricsController, etc.) expose the service to Docker clients and the Wave CLI.
b. Authentication & Authorization Module: Shows modules handling authentication for various registries (e.g., BasicAuthenticationProvider, RegistryAuthService, RegistryCredentialsProvider) which secure access and token management.
c. Container Build & Augmentation Services: Illustrate the service(s) that build or augment images on demand. This includes services related to building container images using given Dockerfiles or Conda packages (seen in the service/builder package) and those for image augmentation (modules in wave/core and blob).
d. Proxy Service: Since disposable containers act as a proxy, include the component that instruments the manifest and redirects container pull requests (e.g., RegistryProxyController and related service components).
e. Blob & Cache Management: The blob service (e.g., BlobCacheService, BlobSigningService) manages caching of built images and signed URLs for secure downloads. Also include caching components that interact with Redis and other storage backends.
f. Rate Limiting & Monitoring: Given the ratelimit packages (e.g., RateLimiterFilter, SpillwayRateLimiter) and metrics controllers/service components, show how incoming requests are throttled and monitored.
g. External Dependencies & Integrations:
• Container Registries: Outbound connections to various registries (Docker Hub, Quay, AWS ECR, AzureCR).
• Redis: Used for caching, rate limiting, state stores, and message queues.
• Kubernetes: Utilized for production deployment and possibly for container builds (as indicated in the README and service/k8s packages).
• Other External Tools: Reference to the Wave CLI, and external vulnerabilities scanners or manifest APIs.
Relationships and Interactions
• The API/Controller layer receives requests for container provisioning. It validates and authenticates incoming requests by consulting the Authentication Module.
• A request for building or augmenting an image is forwarded to the Build Service. This service may use either Docker or Kubernetes build strategies, interacting with Blob Management to retrieve/push container layers.
• For disposable requests, the Proxy Service engages by intercepting the container pull flow, rewriting image manifests, and routing layer downloads between the Docker client and the external registries.
• Caching, state management, and rate limiting services (using Redis) intersect with the Build, Scan, and Proxy services to improve performance and provide resilience.
• Monitoring and metrics components gather performance and usage statistics that flow back to the Metrics Controller for observability.
• External integrations (container registries, cloud storage, etc.) are depicted as external systems that exchange data via defined protocols (e.g., Docker registry v2 API).
Architectural Patterns and Design Principles
• A layered/microkernel pattern is evident where API/Controllers, Services, and Utility/Infrastructure layers are clearly separated.
• Modular design: The codebase is divided into many well-defined packages (auth, builder, blob, counter, etc.) that help in understanding and extending functionality.
• Integration of external services via adapters or factory patterns (e.g., RegistryCredentialsFactory, RedisFactory) promotes loose coupling.
• Use of interception and filter patterns (like in the filters directory) to manage cross-cutting concerns such as tracing, logging, and rate limiting.