Documentation
¶
Overview ¶
Package cache implements GitHub Actions cache protocol backed by S3.
Index ¶
- Constants
- func GenerateCacheToken(secret, jobID, instanceID, scope string) string
- func ParseCacheToken(token string) (jobID, instanceID, scope string, ok bool)
- func ScopeFromContext(ctx context.Context) string
- func ValidateCacheToken(secret, token string) bool
- type AuthMiddleware
- type Handler
- func (h *Handler) CommitCacheEntry(w http.ResponseWriter, r *http.Request, cacheID string)
- func (h *Handler) DownloadCacheArtifact(w http.ResponseWriter, r *http.Request, cacheID string)
- func (h *Handler) GetCacheEntry(w http.ResponseWriter, r *http.Request)
- func (h *Handler) IsAuthEnabled() bool
- func (h *Handler) RegisterRoutes(mux *http.ServeMux)
- func (h *Handler) ReserveCacheEntry(w http.ResponseWriter, r *http.Request)
- type Metrics
- type PresignAPI
- type S3API
- type Server
- func NewServer(cfg aws.Config, bucketName string) *Server
- func NewServerWithClients(s3Client S3API, presignClient PresignAPI, bucketName string) *Server
- func NewServerWithClientsAndScope(s3Client S3API, presignClient PresignAPI, bucketName, scope string) *Server
- func NewServerWithScope(cfg aws.Config, bucketName, scope string) *Server
- func (s *Server) CommitCacheEntry(_ context.Context, _ string) error
- func (s *Server) CreateCacheEntry(_ context.Context, key string, version string) (string, error)
- func (s *Server) GeneratePresignedURL(ctx context.Context, key string, method string) (string, error)
- func (s *Server) GetCacheEntry(ctx context.Context, keys []string, version string) (string, bool, error)
- func (s *Server) SetScope(scope string)
- func (s *Server) WithScope(scope string) *Server
Constants ¶
const (
// CacheTokenHeader is the HTTP header used to pass the cache authentication token.
CacheTokenHeader = "X-Cache-Token"
)
Variables ¶
This section is empty.
Functions ¶
func GenerateCacheToken ¶
GenerateCacheToken creates a self-contained HMAC token for cache authentication. Token format: base64url(job_id:instance_id:scope).hmac_hex This allows stateless validation - the server can extract the payload and verify the signature. The scope parameter should be in "org/repo" format for repository-scoped caching.
func ParseCacheToken ¶
ParseCacheToken extracts job_id, instance_id, and scope from a self-contained token. Returns empty strings if token is malformed. Scope may be empty for backwards compatibility with older tokens.
func ScopeFromContext ¶ added in v1.0.0
ScopeFromContext extracts the cache scope from a request context. Returns empty string if no scope was set.
func ValidateCacheToken ¶
ValidateCacheToken verifies that the provided token has a valid HMAC signature. This is stateless - it extracts the payload from the token and recomputes the HMAC.
Types ¶
type AuthMiddleware ¶
type AuthMiddleware struct {
// contains filtered or unexported fields
}
AuthMiddleware wraps an http.Handler to require cache token authentication. This is completely stateless - no token registration required.
func NewAuthMiddleware ¶
func NewAuthMiddleware(secret string) *AuthMiddleware
NewAuthMiddleware creates authentication middleware for cache endpoints. If secret is empty, authentication is disabled (for backwards compatibility).
func (*AuthMiddleware) IsEnabled ¶
func (m *AuthMiddleware) IsEnabled() bool
IsEnabled returns whether authentication is enabled.
func (*AuthMiddleware) Wrap ¶
func (m *AuthMiddleware) Wrap(next http.Handler) http.Handler
Wrap returns an http.Handler that validates the cache token before calling the next handler. If valid, it extracts the scope from the token and stores it in the request context.
func (*AuthMiddleware) WrapFunc ¶
func (m *AuthMiddleware) WrapFunc(next http.HandlerFunc) http.Handler
WrapFunc is a convenience method for wrapping http.HandlerFunc.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler implements HTTP endpoints for GitHub Actions cache protocol.
func NewHandlerWithAuth ¶
NewHandlerWithAuth creates a new cache handler with authentication and metrics. Authentication is stateless - no token registration required on the server.
func NewHandlerWithMetrics ¶
NewHandlerWithMetrics creates a new cache handler with metrics support.
func (*Handler) CommitCacheEntry ¶
CommitCacheEntry commits a cache entry after upload via PATCH /_apis/artifactcache/caches/{id}.
func (*Handler) DownloadCacheArtifact ¶
DownloadCacheArtifact redirects to pre-signed S3 URL via GET /_artifacts/{id}.
func (*Handler) GetCacheEntry ¶
func (h *Handler) GetCacheEntry(w http.ResponseWriter, r *http.Request)
GetCacheEntry retrieves cache metadata via GET /_apis/artifactcache/cache.
func (*Handler) IsAuthEnabled ¶
IsAuthEnabled returns whether cache authentication is enabled.
func (*Handler) RegisterRoutes ¶
RegisterRoutes registers all cache API routes with the HTTP mux. If authentication is enabled, all cache endpoints require a valid token.
func (*Handler) ReserveCacheEntry ¶
func (h *Handler) ReserveCacheEntry(w http.ResponseWriter, r *http.Request)
ReserveCacheEntry reserves a cache entry for upload via POST /_apis/artifactcache/caches.
type Metrics ¶
type Metrics interface {
PublishCacheHit(ctx context.Context) error
PublishCacheMiss(ctx context.Context) error
}
Metrics defines the interface for publishing cache metrics.
type PresignAPI ¶
type PresignAPI interface {
PresignPutObject(ctx context.Context, params *s3.PutObjectInput, optFns ...func(*s3.PresignOptions)) (*v4.PresignedHTTPRequest, error)
PresignGetObject(ctx context.Context, params *s3.GetObjectInput, optFns ...func(*s3.PresignOptions)) (*v4.PresignedHTTPRequest, error)
}
PresignAPI defines pre-signing operations for S3 URLs.
type S3API ¶
type S3API interface {
HeadObject(ctx context.Context, params *s3.HeadObjectInput, optFns ...func(*s3.Options)) (*s3.HeadObjectOutput, error)
ListObjectsV2(ctx context.Context, params *s3.ListObjectsV2Input, optFns ...func(*s3.Options)) (*s3.ListObjectsV2Output, error)
}
S3API defines S3 operations required for cache server.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server implements GitHub Actions cache protocol using S3 backend.
func NewServerWithClients ¶
func NewServerWithClients(s3Client S3API, presignClient PresignAPI, bucketName string) *Server
NewServerWithClients creates a cache server with custom clients for testing.
func NewServerWithClientsAndScope ¶ added in v1.0.0
func NewServerWithClientsAndScope(s3Client S3API, presignClient PresignAPI, bucketName, scope string) *Server
NewServerWithClientsAndScope creates a cache server with custom clients and scope for testing.
func NewServerWithScope ¶ added in v1.0.0
NewServerWithScope creates a new cache server with repository scoping. Scope should be in format "org/repo" for repo-level isolation or "org" for org-level sharing.
func (*Server) CommitCacheEntry ¶
CommitCacheEntry finalizes the cache entry No-op for S3 backend since uploads are atomic via pre-signed URLs
func (*Server) CreateCacheEntry ¶
CreateCacheEntry prepares for a new cache upload
func (*Server) GeneratePresignedURL ¶
func (s *Server) GeneratePresignedURL(ctx context.Context, key string, method string) (string, error)
GeneratePresignedURL generates a pre-signed URL for uploading or downloading cache artifacts
func (*Server) GetCacheEntry ¶
func (s *Server) GetCacheEntry(ctx context.Context, keys []string, version string) (string, bool, error)
GetCacheEntry checks if a cache entry exists (metadata lookup) GitHub Actions cache protocol uses keys array as primary + restore-keys fallbacks. The first key is treated as an exact match, subsequent keys support prefix matching.
Source Files