Skip to main content

@signapps/artifact-storage

A storage abstraction for release artifacts (tarballs + manifests), with pluggable local filesystem and Cloudflare R2 (S3-compatible) backends.

  • Workspace: packages/artifact-storage
  • Build: tsc → dist/

Provider interface​

interface ArtifactStorageProvider {
	upload(key, body, contentType?): Promise<void>;
	read(key): Promise<Buffer>;
	exists(key): Promise<boolean>;
	getDownloadUrl(key, expiresInSeconds?): Promise<string>;
	delete(key): Promise<void>;
	buildPath(segments, filename): string;
}

resolveArtifactStorageProvider() picks the backend from the ARTIFACT_STORAGE_MODE env var (default s3):

BackendDetail
LocalWrites under a base dir (default home-assistant/.local-artifacts); getDownloadUrl returns a file:// URL. Used for local dev (ARTIFACT_STORAGE_MODE=local).
S3 / R2AWS SDK S3 client pointed at the Cloudflare R2 endpoint; credentials from R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET; getDownloadUrl returns a presigned URL (1h default).

Key layout​

Artifact keys are built from typed segments:

modules/{moduleName}/{version[-channel]}/module.tar.gz
modules/{moduleName}/{version[-channel]}/manifest.json
customers/{customerKey}/{version[-channel]}/customer.tar.gz
customers/{customerKey}/{version[-channel]}/manifest.json
builds/{lockHash}/customer-build.tar.gz

Stable versions omit the channel suffix; beta/alpha append -beta/-alpha.

Exports​

Segment types (ModuleArtifactSegments, CustomerArtifactSegments, BuildArtifactSegments), path helpers (buildArtifactPath, customerBuildKey, versionPathSegment), provider factories (createS3ArtifactStorageProvider, createLocalArtifactStorageProvider, resolveArtifactStorageProvider), and readLocalArtifact.

Consumed by​

@signapps/ha-tooling and the API server (compose builds).