Fallback Provider

FallbackProvider tries providers in order so operations can continue when the primary provider is unavailable.

Use fallback for controlled failover, not as a way to hide incompatible provider boundaries. Providers in a fallback chain must preserve the metadata required by the workflows you use.

Example

import { createMeshkit, FallbackProvider, HttpIpfsProvider, GatewayRetrievalProvider } from "@meshkit/core";

const primary = new HttpIpfsProvider({
  ipfsApiUrl: process.env.MESHKIT_IPFS_API!,
  metadataApiUrl: process.env.MESHKIT_METADATA_API!,
  token: process.env.MESHKIT_PROVIDER_TOKEN,
});

const gateway = new GatewayRetrievalProvider({
  storage: primary,
  gatewayUrl: "https://gateway.example",
});

const mesh = await createMeshkit({
  provider: new FallbackProvider([primary, gateway]),
});

const file = await mesh.files.put("fallback.txt", "written through first healthy provider");

console.log(file.proof.provider);

Good Uses

Try primary storage first and gateway retrieval second.
Keep read paths available during a temporary provider outage.
Collect logs that show which provider handled an operation.
Stage provider migration while keeping a known fallback available.

Risky Uses

Mixing providers that do not share metadata.
Falling back from a production provider to local-dev.
Hiding repeated provider failures instead of alerting.
Assuming fallback means the same CID is available everywhere.

Metadata Compatibility

Fallback works best when providers agree on:

encrypted byte availability
proof records
capsule and revocation records
mailbox records
sync job records
vault and capability records

If only bytes are shared, features like sharing, messages, and sync can still fail.

Operational Notes

Log which provider handled each operation.
Alert when fallback is used, especially for writes.
Validate read and write behavior with the primary unavailable.
Keep retry limits explicit so failures do not mask data placement mistakes.