Skip to main content
Version: Next

Options

Blobber uses functional options for configuration.

Client Options​

Options passed to NewClient().

WithCredentials​

func WithCredentials(registryHost, username, password string) ClientOption

Sets explicit credentials for a specific registry.

ParameterTypeDescription
registryHoststringRegistry hostname (e.g., ghcr.io)
usernamestringUsername or token name
passwordstringPassword or token

Example:

client, err := blobber.NewClient(
    blobber.WithCredentials("ghcr.io", "username", os.Getenv("GITHUB_TOKEN")),
)

WithInsecure​

func WithInsecure(insecure bool) ClientOption

Allows connections without TLS.

ParameterTypeDefaultDescription
insecureboolfalseAllow insecure connections

Example:

client, err := blobber.NewClient(
    blobber.WithInsecure(true),
)

WithLogger​

func WithLogger(logger *slog.Logger) ClientOption

Sets a structured logger for debug output.

ParameterTypeDescription
logger*slog.LoggerLogger instance

Example:

client, err := blobber.NewClient(
    blobber.WithLogger(slog.Default()),
)

WithUserAgent​

func WithUserAgent(ua string) ClientOption

Sets a custom User-Agent header for HTTP requests.

ParameterTypeDescription
uastringUser-Agent string

Example:

client, err := blobber.NewClient(
    blobber.WithUserAgent("myapp/1.0.0"),
)

WithCacheDir​

func WithCacheDir(path string) ClientOption

Enables blob caching at the specified directory.

ParameterTypeDescription
pathstringCache directory path

Example:

client, err := blobber.NewClient(
    blobber.WithCacheDir("/tmp/blobber-cache"),
)

WithCacheVerifyOnRead​

func WithCacheVerifyOnRead(enabled bool) ClientOption

Re-hashes cached blobs on cache hits to detect tampering. Incompatible with WithLazyLoading.

ParameterTypeDefaultDescription
enabledboolfalseVerify cached blobs on read

Example:

client, err := blobber.NewClient(
    blobber.WithCacheVerifyOnRead(true),
)

WithLazyLoading​

func WithLazyLoading(enabled bool) ClientOption

Enables on-demand blob fetching for OpenImage.

ParameterTypeDefaultDescription
enabledboolfalseEnable lazy loading

When enabled, OpenImage fetches only the TOC initially, downloading file contents on-demand.

Example:

client, err := blobber.NewClient(
    blobber.WithLazyLoading(true),
)

WithDescriptorCache​

func WithDescriptorCache(enabled bool) ClientOption

Enables in-memory caching of layer descriptors.

ParameterTypeDefaultDescription
enabledboolfalseEnable descriptor caching

Note: May return stale results for mutable tags.

WithBackgroundPrefetch​

func WithBackgroundPrefetch(enabled bool) ClientOption

Enables background downloading of complete blobs during lazy loading.

ParameterTypeDefaultDescription
enabledboolfalseEnable background prefetch

WithSigner​

func WithSigner(s Signer) ClientOption

Configures signing for push operations. When set, Push will sign the artifact after uploading and store the signature as an OCI referrer.

ParameterTypeDescription
sSignerSigner implementation (e.g., from sigstore package)

Example:

import "github.com/meigma/blobber/sigstore"

signer, _ := sigstore.NewSigner(
    sigstore.WithEphemeralKey(),
    sigstore.WithFulcio("https://fulcio.sigstore.dev"),
    sigstore.WithRekor("https://rekor.sigstore.dev"),
)

client, err := blobber.NewClient(
    blobber.WithSigner(signer),
)

WithVerifier​

func WithVerifier(v Verifier) ClientOption

Configures verification for pull and open operations. When set, Pull and OpenImage will verify signatures before returning data.

ParameterTypeDescription
vVerifierVerifier implementation (e.g., from sigstore package)

Returns:

  • ErrNoSignature if no signature is found
  • ErrSignatureInvalid if verification fails

Example:

import "github.com/meigma/blobber/sigstore"

verifier, _ := sigstore.NewVerifier(
    sigstore.WithIdentity(
        "https://accounts.google.com",
        "developer@company.com",
    ),
)

client, err := blobber.NewClient(
    blobber.WithVerifier(verifier),
)

Push Options​

Options passed to Client.Push().

WithCompression​

func WithCompression(c Compression) ClientOption

Sets the compression algorithm.

ParameterTypeDescription
cCompressionCompression algorithm

Compression constructors:

blobber.GzipCompression() // Default
blobber.ZstdCompression() // Better ratios, faster decompression

Example:

digest, err := client.Push(ctx, ref, files,
    blobber.WithCompression(blobber.ZstdCompression()),
)

WithAnnotations​

func WithAnnotations(annotations map[string]string) PushOption

Sets OCI annotations on the pushed manifest.

ParameterTypeDescription
annotationsmap[string]stringKey-value annotation pairs

Example:

digest, err := client.Push(ctx, ref, files,
    blobber.WithAnnotations(map[string]string{
        "org.opencontainers.image.source": "https://github.com/org/repo",
        "org.opencontainers.image.version": "1.0.0",
    }),
)

WithMediaType​

func WithMediaType(mt string) PushOption

Sets a custom media type for the layer.

ParameterTypeDescription
mtstringMedia type string

Pull Options​

Options passed to Client.Pull().

WithExtractLimits​

func WithExtractLimits(limits ExtractLimits) PullOption

Sets safety limits for extraction.

ExtractLimits fields:

FieldTypeDefaultDescription
MaxFilesint100,000Maximum file count
MaxTotalSizeint6410 GBMaximum total bytes
MaxFileSizeint641 GBMaximum per-file bytes

Example:

err := client.Pull(ctx, ref, destDir,
    blobber.WithExtractLimits(blobber.ExtractLimits{
        MaxFiles:     1000,
        MaxTotalSize: 100 * 1024 * 1024, // 100MB
        MaxFileSize:  10 * 1024 * 1024,  // 10MB
    }),
)

See Also​