• Ask for a path, get the file. One call reads or writes text, bytes or a stream. There is no SDK to learn for each service.
• Every provider behaves the same. Path resolution, defaults and errors do not change with the provider: a missing file is StoragePathNotFoundError, code strg_path_not_found, on a local disk, on S3, on GCP Storage and over SFTP. All four pass the same contract test suite.
• Change providers, not code. Moving from S3 to GCP Storage changes the provider, its options and the installed package. Every read_contentreadContent call stays as written.
• Tests without the cloud. The local-filesystem provider follows the same contract, so tests and CI make the same calls against a directory, with no network and no credentials.
• What a service cannot do, the call says. A signed URL on a local disk raises StorageCapabilityNotSupportedError instead of returning a link that would not work.
• Python and TypeScript, one contract. Each follows its own convention — read_content, readContent — and both share the behavior, the defaults and the error codes.

• Peça um caminho, receba o arquivo. Uma chamada lê ou escreve texto, bytes ou um stream. Não há SDK para aprender a cada serviço.
• Todo armazenamento se comporta igual. A resolução de caminhos, os defaults e os erros não mudam com o armazenamento: um arquivo ausente é StoragePathNotFoundError, código strg_path_not_found, num disco local, no S3, no GCP Storage e via SFTP. Os quatro passam pela mesma suíte de testes de contrato.
• Troque o armazenamento, não o código. Sair do S3 para o GCP Storage muda o armazenamento, suas opções e o pacote instalado. Toda chamada a read_contentreadContent continua como foi escrita.
• Testes sem nuvem. O armazenamento local-filesystem segue o mesmo contrato, então testes e CI fazem as mesmas chamadas contra um diretório, sem rede e sem credencial.
• O que um serviço não faz, a chamada diz. Uma URL assinada num disco local levanta StorageCapabilityNotSupportedError em vez de devolver um link que não funcionaria.
• Python e TypeScript, um contrato. Cada um segue a convenção da sua linguagem — read_content, readContent — e os dois compartilham comportamento, defaults e códigos de erro.

from storage_kernel.factory import (
    CreateStorageClientConfig,
    StorageLocation,
    StoragePathNotFoundError,
    create_storage_client,
)
from storage_kernel.provider_aws_s3 import (
    AwsS3StorageProviderOptions,
)

storage = await create_storage_client(
    CreateStorageClientConfig(
        provider_name="aws-s3",
        location=StorageLocation(
            bucket="app-files",
            prefix="reports",
        ),
        options=AwsS3StorageProviderOptions(
            region="us-east-1",
        ),
    )
)

try:
    text = await storage.read_content("2026/summary.csv")
except StoragePathNotFoundError as error:
    error.code  # "strg_path_not_found", on any provider

from storage_kernel.factory import (
    CreateStorageClientConfig,
    StorageLocation,
    StoragePathNotFoundError,
    create_storage_client,
)
from storage_kernel.provider_gcp_storage import (
    GcpStorageProviderOptions,
)

storage = await create_storage_client(
    CreateStorageClientConfig(
        provider_name="gcp-storage",
        location=StorageLocation(
            bucket="app-files",
            prefix="reports",
        ),
        options=GcpStorageProviderOptions(
            project_id="my-gcp-project",
        ),
    )
)

try:
    text = await storage.read_content("2026/summary.csv")
except StoragePathNotFoundError as error:
    error.code  # "strg_path_not_found", on any provider

from storage_kernel.factory import (
    CreateStorageClientConfig,
    StorageLocation,
    StoragePathNotFoundError,
    create_storage_client,
)

storage = await create_storage_client(
    CreateStorageClientConfig(
        provider_name="local-filesystem",
        location=StorageLocation(
            directory="./var/storage",
            prefix="reports",
        ),
    )
)

try:
    text = await storage.read_content("2026/summary.csv")
except StoragePathNotFoundError as error:
    error.code  # "strg_path_not_found", on any provider

import {
    StoragePathNotFoundError,
    createStorageClient,
} from '@storage-kernel/factory';

const storage = await createStorageClient({
    providerName: 'aws-s3',
    location: { bucket: 'app-files', prefix: 'reports' },
    options: { region: 'us-east-1' },
});

try {
    const text = await storage.readContent('2026/summary.csv');
} catch (error) {
    if (error instanceof StoragePathNotFoundError) {
        error.code; // 'strg_path_not_found', on any provider
    }
}

import {
    StoragePathNotFoundError,
    createStorageClient,
} from '@storage-kernel/factory';

const storage = await createStorageClient({
    providerName: 'gcp-storage',
    location: { bucket: 'app-files', prefix: 'reports' },
    options: { projectId: 'my-gcp-project' },
});

try {
    const text = await storage.readContent('2026/summary.csv');
} catch (error) {
    if (error instanceof StoragePathNotFoundError) {
        error.code; // 'strg_path_not_found', on any provider
    }
}

import {
    StoragePathNotFoundError,
    createStorageClient,
} from '@storage-kernel/factory';

const storage = await createStorageClient({
    providerName: 'local-filesystem',
    location: {
        directory: './var/storage',
        prefix: 'reports',
    },
});

try {
    const text = await storage.readContent('2026/summary.csv');
} catch (error) {
    if (error instanceof StoragePathNotFoundError) {
        error.code; // 'strg_path_not_found', on any provider
    }
}

Step 1 · install the factory

Passo 1 · instale a factory

Your code imports everything from the factory: the location, the option classes, the errors and the types of the contract come through it. The contract and the shared core install with it, as dependencies. No provider yet — that is step 2, and it is a separate distribution so a service that only touches S3 never pulls a Google SDK or an SSH library.

O seu código importa tudo da factory: a location, as classes de opções, os erros e os tipos do contrato vêm por ela. O contrato e o core compartilhado são instalados junto, como dependências. Nenhum armazenamento ainda — isso é o passo 2, e ele é uma distribuição separada, então um serviço que só toca S3 nunca baixa um SDK do Google nem uma biblioteca de SSH.

contracts depends on nothing. A consumer that only declares types or catches storage errors installs that one package alone.

contracts não depende de nada. Quem só declara tipos ou captura erros de storage instala apenas esse pacote.

$ uv add storage-kernel-factory

$ npm install @storage-kernel/factory

Normalization

Normalização

The same everywhere: backslashes become /, duplicate separators collapse, a leading ./ and any leading or trailing slash are dropped, and a .. segment is rejected with StorageInvalidPathError.

Igual em todo lugar: contrabarras viram /, separadores duplicados colapsam, um ./ inicial e qualquer barra no começo ou no fim caem fora, e um segmento .. é rejeitado com StorageInvalidPathError.

The local provider adds one more check after resolving: the absolute result has to stay below the configured directory, so a symlink or an oddly encoded path cannot walk out of it.

O armazenamento local acrescenta mais uma checagem depois de resolver: o resultado absoluto precisa continuar abaixo do diretório configurado, então um symlink ou um caminho com encoding estranho não consegue sair dele.

An operation-level location replaces the client's entirely. It is not merged field by field, so naming another bucket for one call cannot leave the old prefix quietly attached.

Uma location no nível da operação substitui a do client por inteiro. Ela não é mesclada campo a campo, então nomear outro bucket numa chamada não deixa o prefix antigo grudado em silêncio.

from storage_kernel.factory import (
    StorageLocation,
    StorageOperationOptions,
)

# archive/reports/2026/summary.csv — another bucket,
# and the prefix comes from this location, not the client's
await storage.read_binary(
    "2026/summary.csv",
    StorageOperationOptions(
        location=StorageLocation(
            bucket="archive", prefix="reports"
        )
    ),
)

# rejected: StorageInvalidPathError
await storage.read_binary("../etc/passwd")

// archive/reports/2026/summary.csv — another bucket,
// and the prefix comes from this location, not the client's
await storage.readBinary(
    '2026/summary.csv',
    { location: { bucket: 'archive', prefix: 'reports' } },
);

// rejected: StorageInvalidPathError
await storage.readBinary('../etc/passwd');

Whole values

Valores inteiros

Text goes through send_contentsendContent and read_contentreadContent, UTF-8 unless encoding says otherwise. Bytes go through send_binarysendBinary and read_binaryreadBinary.

Texto passa por send_contentsendContent e read_contentreadContent, em UTF-8 a menos que encoding diga outra coisa. Bytes passam por send_binarysendBinary e read_binaryreadBinary.

A full read buffers the entire payload, which is exactly why the stream methods exist beside them. A missing file is StoragePathNotFoundError, on every provider.

Uma leitura completa carrega o payload inteiro na memória, que é justamente por que os métodos de stream existem ao lado. Um arquivo ausente é StoragePathNotFoundError, em todo armazenamento.

A write can carry content_typecontentType and object metadata, and can turn overwrite off for that call alone.

Uma escrita pode carregar content_typecontentType e metadata do objeto, e pode desligar o overwrite só naquela chamada.

from storage_kernel.factory import SendContentOptions

await storage.send_content(
    "docs/readme.md",
    "# Hello",
    SendContentOptions(
        content_type="text/markdown",
        overwrite=False,
    ),
)

text = await storage.read_content("docs/readme.md")
data = await storage.read_binary("images/avatar.png")

await storage.sendContent(
    'docs/readme.md',
    '# Hello',
    { contentType: 'text/markdown', overwrite: false },
);

const text = await storage.readContent('docs/readme.md');
const data = await storage.readBinary('images/avatar.png');

Streams

Streams

read_streamreadStream hands back an async byte iterable that carries close(). Reading to the end releases it; a reader that stops early has to call close(), which is idempotent, so calling it anyway is always correct.

read_streamreadStream devolve um iterável assíncrono de bytes que carrega close(). Ler até o fim o libera; quem para antes precisa chamar close(), que é idempotente, então chamá-lo de qualquer jeito está sempre certo.

create_upload_streamcreateUploadStream hands back a writable handle with five methods: write, write_textwriteText, write_text_linewriteTextLine, then close() to finish or abort() to discard. close() waits for the provider to actually finish, and after either one another write fails with a normalized error rather than quietly doing nothing.

create_upload_streamcreateUploadStream devolve um handle de escrita com cinco métodos: write, write_textwriteText, write_text_linewriteTextLine, e então close() para concluir ou abort() para descartar. close() espera o armazenamento realmente concluir, e depois de qualquer um dos dois outra escrita falha com um erro normalizado em vez de não fazer nada em silêncio.

send_streamsendStream takes text, bytes or a stream and writes it in parts through that same handle, never buffering the whole payload.

send_streamsendStream recebe texto, bytes ou um stream e escreve em partes por esse mesmo handle, sem nunca acumular o payload inteiro.

On S3 the provider runs a multipart upload of part_size parts, tuned by MultipartUploadOptions with queue_size and leave_parts_on_error; enabled=False buffers to a single PutObject. On GCP Storage the upload is resumable, and part_size sets its chunk size, 256 KiB at least.

No S3 o armazenamento faz um upload multipart em partes de part_size, ajustado por MultipartUploadOptions com queue_size e leave_parts_on_error; enabled=False acumula tudo num único PutObject. No GCP Storage o upload é retomável, e part_size define o tamanho de cada pedaço, no mínimo 256 KiB.

On S3 this is the SDK's managed upload, started with the stream. MultipartUploadOptions tunes partSize, queueSize and leavePartsOnError; enabled: false buffers to a single PutObject. On GCP Storage, enabled maps to a resumable upload.

No S3 isso é o upload gerenciado do SDK, iniciado junto com o stream. MultipartUploadOptions ajusta partSize, queueSize e leavePartsOnError; enabled: false acumula tudo num único PutObject. No GCP Storage, enabled vira um upload retomável.

# read without holding the file in memory
stream = await storage.read_stream("archive/2026.zip")
try:
    async for chunk in stream:
        process(chunk)
finally:
    await stream.close()

# write progressively; close() commits, abort() discards
upload = await storage.create_upload_stream("logs/app.ndjson")
try:
    for event in events:
        await upload.write_text_line(json.dumps(event))
    await upload.close()
except BaseException:
    await upload.abort()
    raise

// read without holding the file in memory
const stream = await storage.readStream('archive/2026.zip');
try {
    for await (const chunk of stream) {
        process(chunk);
    }
} finally {
    await stream.close();
}

// write progressively; close() commits, abort() discards
const upload = await storage.createUploadStream(
    'logs/app.ndjson',
);
try {
    for (const event of events) {
        await upload.writeTextLine(JSON.stringify(event));
    }
    await upload.close();
} catch (error) {
    await upload.abort(error);
    throw error;
}

read_directoryreadDirectory returns entries sorted by path, with the configured prefix already stripped, so a listing reads in the same terms the call was written in.

read_directoryreadDirectory devolve entradas ordenadas por caminho, já sem o prefix configurado, então a listagem se lê nos mesmos termos em que a chamada foi escrita.

Both defaults are exported rather than hidden: DEFAULT_READ_DIRECTORY_RECURSIVE and DEFAULT_READ_DIRECTORY_INCLUDE_DIRECTORIES, both true.

Os dois defaults são exportados em vez de escondidos: DEFAULT_READ_DIRECTORY_RECURSIVE e DEFAULT_READ_DIRECTORY_INCLUDE_DIRECTORIES, os dois verdadeiros.

On S3 and GCP Storage a directory exists when at least one object lives below the prefix — that is what check_path_existscheckPathExists answers there.

No S3 e no GCP Storage um diretório existe quando ao menos um objeto mora abaixo do prefixo — é isso que check_path_existscheckPathExists responde ali.

get_file_infogetFileInfo does not raise for a path that is not there. It returns the path you asked for with exists=Falseexists: false, because "is it there" and "something went wrong" are different questions.

get_file_infogetFileInfo não levanta erro para um caminho que não está lá. Devolve o caminho que você pediu com exists=Falseexists: false, porque "está lá?" e "deu errado?" são perguntas diferentes.

Deleting a directory is recursive by default. Non-recursively, a cloud provider refuses while nested objects still exist rather than deleting part of the tree.

Remover um diretório é recursivo por padrão. Sem recursão, um armazenamento de nuvem recusa enquanto ainda houver objetos aninhados, em vez de apagar parte da árvore.

from storage_kernel.factory import ReadDirectoryOptions

# everything below reports/, files and directories
entries = await storage.read_directory("reports")

# only the files directly inside reports/
files = await storage.read_directory(
    "reports",
    ReadDirectoryOptions(
        recursive=False, include_directories=False
    ),
)

total = await storage.get_directory_content_length("reports")
info = await storage.get_file_info("reports/2026/summary.csv")
# info.exists, info.content_length, info.updated_at

// everything below reports/, files and directories
const entries = await storage.readDirectory('reports');

// only the files directly inside reports/
const files = await storage.readDirectory(
    'reports',
    { recursive: false, includeDirectories: false },
);

const total = await storage.getDirectoryContentLength(
    'reports',
);
const info = await storage.getFileInfo(
    'reports/2026/summary.csv',
);
// info.exists, info.contentLength, info.updatedAt

URLs and copies

URLs e cópias

create_signed_urlcreateSignedUrl takes an action — read, write or delete — and expires_in_secondsexpiresInSeconds. A signed write forwards content_typecontentType and string metadata to the signature.

create_signed_urlcreateSignedUrl recebe uma action — read, write ou delete — e expires_in_secondsexpiresInSeconds. Uma escrita assinada encaminha content_typecontentType e metadados de string para a assinatura.

Both clouds sign with Signature Version 4, so a URL lives seven days at most. A boto3 client you inject has to be built with Config(signature_version="s3v4").

As duas nuvens assinam com a Signature Version 4, então uma URL vive no máximo sete dias. Um client boto3 que você injeta precisa ser construído com Config(signature_version="s3v4").

get_public_urlgetPublicUrl percent-encodes each path segment and keeps /, so a # or ? in a name survives. It resolves a URL and nothing else: it does not change permissions and does not promise the object is readable. Unlike a signed URL it carries no expiry, because a public URL is public for as long as the object is.

get_public_urlgetPublicUrl aplica percent-encoding em cada segmento e preserva /, então um # ou ? num nome sobrevive. Ela resolve uma URL e nada mais: não muda permissões nem promete que o objeto é legível. Diferente de uma URL assinada, ela não tem validade, porque uma URL pública é pública enquanto o objeto for.

native_copy_filenativeCopyFile copies inside one provider using its own mechanism — CopyObject on S3, a filesystem copy locally, and over SFTP a remote read stream piped into a remote write streama remote read into memory and a remote write. The destination resolves from destination_locationdestinationLocation, then the operation's location, then the client's, so a copy given only a location lands beside its source. The overwrite check always runs at the destination.

native_copy_filenativeCopyFile copia dentro de um armazenamento usando o mecanismo dele — CopyObject no S3, uma cópia de filesystem localmente, e no SFTP um stream de leitura remoto canalizado para um stream de escrita remotouma leitura remota para a memória e uma escrita remota. O destino resolve a partir de destination_locationdestinationLocation, depois da location da operação, depois da do client, então uma cópia que só recebe uma location cai ao lado da origem. A verificação de overwrite sempre roda no destino.

from storage_kernel.factory import (
    CreateSignedUrlOptions,
    NativeCopyFileOptions,
    StorageLocation,
    StorageSignedUrlAction,
)

signed = await storage.create_signed_url(
    "2026/summary.csv",
    CreateSignedUrlOptions(
        action=StorageSignedUrlAction.READ,
        expires_in_seconds=900,
    ),
)
# signed.url, signed.expires_at, signed.method

await storage.native_copy_file(
    "2026/summary.csv",
    "2026/summary.csv",
    NativeCopyFileOptions(
        destination_location=StorageLocation(bucket="archive"),
    ),
)

const signed = await storage.createSignedUrl(
    '2026/summary.csv',
    { action: 'read', expiresInSeconds: 900 },
);
// signed.url, signed.expiresAt, signed.method

await storage.nativeCopyFile(
    '2026/summary.csv',
    '2026/summary.csv',
    { destinationLocation: { bucket: 'archive' } },
);

Credentials and lifecycle

Credenciais e ciclo de vida

Credentials are explicit when you pass them and fall back to the cloud SDK's own chain when you do not — the AWS provider chain, or Application Default Credentials on GCP.

As credenciais são explícitas quando você as passa, e caem para a própria cadeia do SDK da nuvem quando você não passa — a cadeia de credenciais da AWS, ou as Application Default Credentials no GCP.

Injecting a client keeps that SDK client under your lifecycle. close() releases only what the kernel created: the S3 client and the SFTP connection it opened, and the Google client it built. On GCP it is a no-op, because the SDK exposes no matching operation, and that is stated rather than papered over.

Injetar um client mantém aquele client de SDK sob o seu ciclo de vida. O close() libera apenas o que o kernel criou: o client S3 e a conexão SFTP que ele abriu, e o client do Google que ele construiu. No GCP ele é um no-op, porque o SDK não expõe operação equivalente, e isso é dito em vez de disfarçado.

To configure a client the kernel does build, the S3 provider takes client_optionsclientOptions. It is merged over the provider's own defaults field by field, so setting one bound keeps the others rather than dropping back to the SDK's unbounded ones — and it is ignored entirely when you inject a client, because then the configuration was yours to make.

Para configurar um client que o kernel realmente constrói, o armazenamento S3 recebe client_optionsclientOptions. Ele é mesclado campo a campo sobre os defaults do próprio armazenamento, então definir um limite preserva os outros em vez de cair para os do SDK, que não têm limite — e é totalmente ignorado quando você injeta um client, porque aí a configuração já era sua.

from storage_kernel.factory import (
    StorageClientOptions,
    StorageLocation,
)
from storage_kernel.provider_gcp_storage import (
    GcpStorageProviderOptions,
    create_gcp_storage_client,
)

# the client you built stays yours; close() will not touch it
storage = create_gcp_storage_client(
    StorageClientOptions(
        location=StorageLocation(bucket="app-files"),
    ),
    GcpStorageProviderOptions(
        project_id="my-project",
        client=my_gcs_client,
    ),
)

import {
    GcpStorageClient,
} from '@storage-kernel/provider-gcp-storage';

// the client you built stays yours; close() will not touch it
const storage = new GcpStorageClient(
    { location: { bucket: 'app-files' } },
    { projectId: 'my-project', client: myGcsClient },
);

SFTP host identity

Identidade do host SFTP

The SFTP provider will not open a connection without being told how to verify the server. Exactly one policy is required, and there is no default:

O armazenamento SFTP não abre conexão sem que se diga como verificar o servidor. Exatamente uma política é obrigatória, e não existe default:

• known_hosts_pathknownHostsPath — an OpenSSH known_hosts file.
• host_key_sha256hostKeySha256 — a fingerprint in SHA256:<base64> form.
• host_verifierhostVerifier — your own predicate over the host key.
• dangerously_disable_host_key_verificationdangerouslyDisableHostKeyVerification — the bypass. It accepts any host key, which means accepting a machine-in-the-middle, so it belongs to a disposable local fixture and nowhere else. It is named the way it is so it cannot be switched on without reading what it does.

• known_hosts_pathknownHostsPath — um arquivo known_hosts do OpenSSH.
• host_key_sha256hostKeySha256 — uma fingerprint no formato SHA256:<base64>.
• host_verifierhostVerifier — seu próprio predicado sobre a chave do host.
• dangerously_disable_host_key_verificationdangerouslyDisableHostKeyVerification — o bypass. Ele aceita qualquer chave de host, o que significa aceitar um ataque de intermediário, então serve para uma fixture local descartável e nada mais. O nome é esse justamente para não ser ligado sem se ler o que ele faz.

Two policies at once, or a malformed fingerprint, is a StorageKernelConfigurationError rather than a quiet fallback to something weaker.

Duas políticas ao mesmo tempo, ou uma fingerprint malformada, é um StorageKernelConfigurationError em vez de uma queda silenciosa para algo mais fraco.

Each connection phase is bounded, and the two implementations bound them differently — the SDKs underneath are not the same. Python names four: connect_timeout at 10s, banner_timeout at 15s, auth_timeout at 30s and channel_timeout at 60s. The first one matters most: paramiko leaves the connect socket blocking when no timeout is given, so without it a TCP handshake is bounded only by the operating system. TypeScript takes readyTimeout, in milliseconds, over the whole handshake.

Cada fase da conexão tem um limite, e as duas implementações limitam de formas diferentes — os SDKs por baixo não são os mesmos. O Python nomeia quatro: connect_timeout em 10s, banner_timeout em 15s, auth_timeout em 30s e channel_timeout em 60s. O primeiro é o que mais importa: o paramiko deixa o socket de conexão bloqueante quando nenhum timeout é dado, então sem ele o handshake TCP fica limitado apenas pelo sistema operacional. O TypeScript recebe readyTimeout, em milissegundos, sobre o handshake inteiro.

A failure names both sides: path is always the path you passed, and the message adds the remote one — Storage path not found in sftp: missing.txt (provider path: /upload/missing.txt).

Uma falha nomeia os dois lados: path é sempre o caminho que você passou, e a mensagem acrescenta o remoto — Storage path not found in sftp: missing.txt (provider path: /upload/missing.txt).

SftpStorageProviderOptions(
    host="sftp.example.com",
    username="app",
    private_key_path="/run/secrets/id_ed25519",
    # exactly one of the four policies
    known_hosts_path="/home/app/.ssh/known_hosts",
    # host_key_sha256="SHA256:…",
    # host_verifier=my_verifier,
    # dangerously_disable_host_key_verification=True,
)

const options = {
    host: 'sftp.example.com',
    username: 'app',
    privateKeyPath: '/run/secrets/id_ed25519',
    // exactly one of the four policies
    knownHostsPath: '/home/app/.ssh/known_hosts',
    // hostKeySha256: 'SHA256:…',
    // hostVerifier: myVerifier,
    // dangerouslyDisableHostKeyVerification: true,
};

Three fields identify a failure. name is the class. code is the kernel's own, always present and frozen, the same string in both languages — compare it at a process boundary, where a class cannot travel. provider_codeproviderCode is the vendor's — NoSuchKey on S3, 404 on GCP Storage, SFTP status 2, ENOENT on a local disk, ECONNREFUSED when the service never answered — and is absent when the SDK gave none.

Três campos identificam uma falha. name é a classe. code é do próprio kernel, sempre presente e congelado, a mesma string nas duas linguagens — compare-o numa fronteira entre processos, onde uma classe não viaja. provider_codeproviderCode é o do fornecedor — NoSuchKey no S3, 404 no GCP Storage, status SFTP 2, ENOENT num disco local, ECONNREFUSED quando o serviço nem respondeu — e fica ausente quando o SDK não deu nenhum.

Only not found and permission denied are normalized, because only those two are what a caller branches on without knowing which service is behind the contract. Their message names the provider and the path: Storage path not found in aws-s3: 2026/summary.csv.

Só não encontrado e permissão negada são normalizados, porque só esses dois são aquilo em que quem chama ramifica sem saber qual serviço está atrás do contrato. A mensagem deles nomeia o armazenamento e o caminho: Storage path not found in aws-s3: 2026/summary.csv.

Everything else becomes StorageProviderError and keeps the message the provider produced. Wrapping adds context, it never translates: provider, path and provider_codeproviderCode are attached and the original stays in cause.

Todo o resto vira StorageProviderError e preserva a mensagem que o armazenamento produziu. O wrap acrescenta contexto, nunca traduz: provider, path e provider_codeproviderCode são anexados e o original fica em cause.

An error that already is a StorageKernelError is never re-wrapped and never reclassified. It receives only the context fields it was missing, so a failure raised deep inside a client still reports where it came from.

Um erro que já é StorageKernelError nunca é reembrulhado nem reclassificado. Ele recebe apenas os campos de contexto que faltavam, então uma falha levantada lá no fundo de um client continua dizendo de onde veio.

from storage_kernel.factory import (
    StoragePathNotFoundError,
    StoragePermissionError,
    StorageProviderError,
)

try:
    data = await storage.read_binary("2026/summary.csv")
except StoragePathNotFoundError as error:
    error.code           # "strg_path_not_found"
    error.provider_code  # "NoSuchKey" on aws-s3
    raise
except StoragePermissionError:
    raise
except StorageProviderError as error:
    # the SDK's message, plus provider/path/provider_code
    logger.error("%s (%s)", error, error.provider_code)
    raise

import {
    StoragePathNotFoundError,
    StorageProviderError,
} from '@storage-kernel/factory';

try {
    const data = await storage.readBinary('2026/summary.csv');
} catch (error) {
    if (error instanceof StoragePathNotFoundError) {
        error.code; // 'strg_path_not_found'
        error.providerCode; // 'NoSuchKey' on aws-s3
    } else if (error instanceof StorageProviderError) {
        // the SDK's message, plus provider/path/providerCode
        logger.error(
            `${error.message} (${error.providerCode})`,
        );
    }
    throw error;
}

One line per operation

Uma linha por operação

Pass a logger and the client writes one line per operation. Without one it says nothing: the logger is the only sink, and there is no console fallback. The levels are fixed by the contract, not by each provider: starts and completions on debug, a missing path or an aborted upload on warningwarn, permission and provider failures on error.

Passe um logger e o client escreve uma linha por operação. Sem ele, não diz nada: o logger é o único destino, e não há console de reserva. Os níveis são fixados pelo contrato, não por cada armazenamento: início e conclusão em debug, caminho ausente ou upload abortado em warningwarn, falhas de permissão e do armazenamento em error.

Each line is one sentence naming the operation, the path, the provider and its bucket, directory or prefix — Reading 2026/summary.csv from aws-s3 bucket app-files under reports. Content, credentials and object metadata never appear in it.

Cada linha é uma frase que nomeia a operação, o caminho, o armazenamento e seu bucket, diretório ou prefix — Reading 2026/summary.csv from aws-s3 bucket app-files under reports. Conteúdo, credenciais e metadados de objeto nunca aparecem nela.

Completion is reported when it actually happened: a read stream after it has been fully consumed, an upload after close() succeeded — not when the call returned. A logger may implement any subset of the four levels; a line at a level it lacks is dropped.

A conclusão é reportada quando realmente aconteceu: um stream de leitura depois de consumido por inteiro, um upload depois de close() ter dado certo — não quando a chamada retornou. Um logger pode implementar qualquer subconjunto dos quatro níveis; uma linha num nível que ele não tem é descartada.

Bring your own provider

Traga seu próprio armazenamento

The factory takes a provider_classproviderClass — a class, never an instance — and then any provider name is allowed. If the class declares its own canonical name, it has to match the one you asked for.

A factory recebe um provider_classproviderClass — uma classe, nunca uma instância — e então qualquer nome de armazenamento é permitido. Se a classe declara o próprio nome canônico, ele precisa bater com o que você pediu.

The client is wrapped in the same observability boundary either way, so a provider you wrote logs the same lines as the four that ship here without inheriting anything.

O client é envolvido na mesma fronteira de observabilidade nos dois casos, então um armazenamento que você escreveu emite as mesmas linhas que os quatro que vêm aqui, sem herdar nada.

The testing package exports the portable contract suite these four are held to, so yours can be held to it too. It runs on your own vitest, which it takes as a peer dependency.

O pacote de testing exporta a suíte de contrato portável a que estes quatro são submetidos, então o seu pode ser submetido a ela também. Ela roda no seu próprio vitest, que ele recebe como peer dependency.

storage = await create_storage_client(
    CreateStorageClientConfig(
        provider_name="aws-s3",
        location=StorageLocation(bucket="app-files"),
        logger=logging.getLogger("my-app"),
    )
)

const storage = await createStorageClient({
    providerName: 'aws-s3',
    location: { bucket: 'app-files' },
    logger: console,
});

await create_storage_client(
    CreateStorageClientConfig(
        provider_name="azure-blob",
        provider_class=MyAzureBlobClient,
    )
)

await createStorageClient({
    providerName: 'azure-blob',
    providerClass: MyAzureBlobClient,
});

from storage_kernel.testing import assert_client_contract

await assert_client_contract(storage)

import {
    defineClientContractTests,
} from '@storage-kernel/testing';

defineClientContractTests('azure-blob', {
    createClient: () => new MyAzureBlobClient(),
});