Raw blocksVoor enkele bestanden. Eenvoudiger, minder overhead. Gebruikt voor individuele assets of kleine bestanden.
4. Cache-strategie
4.1 Cache-types
| Type | Cache-duur | Reden | Implementatie |
| Immutable CID | Oneindig | CID = content hash. Na verificatie = permanent geldig. | IndexedDB (Helia) + SW-cache |
| Mutable pointer (IPNS) | 5 minuten | Kan wijzigen, frequente herverificatie. | SW-cache met TTL |
| Gateway response | Per Cache-Control headers | Respecteer gateway-instellingen. | SW-cache |
4.2 Immutable cache-regels
- Bij first fetch: Hash-verificatie → sla op in IndexedDB (Helia) + SW-cache.
- Bij subsequent fetch: Check IndexedDB → hit? → return (zero-network). Miss? → ga naar gateway.
- Geen expiratie: Immutable CIDs verlopen nooit. Na verificatie = permanent geldig.
- Opschoning: Alleen bij emergency cleanup (geheugendruk) of expliciete unpin.
4.3 Mutable cache-regels
- TTL: 5 minuten. Na 5 min: opnieuw fetchen + verifiëren.
- Update: Bij nieuwe content: hash-verificatie → update cache.
- IPNS-resolutie: Eerst IPNS resolver, dan CID, dan fetch + verifieer.
5. Gateway-allowlist beheer
5.1 Configuratie
{
"gateways": [
{
"name": "kubo-primary",
"url": "http://kubo.internal:8080",
"preferred": true,
"timeout": 5000,
"retryCount": 2,
"healthCheck": {
"interval": 30000,
"endpoint": "/api/v0/id"
}
},
{
"name": "kubo-replica",
"url": "http://kubo-replica.internal:8080",
"preferred": false,
"timeout": 5000,
"retryCount": 2
},
{
"name": "provider-a",
"url": "https://provider-a.example.com",
"preferred": false,
"timeout": 10000,
"retryCount": 1,
"auth": {
"type": "bearer",
"token": "{env:PROVIDER_A_TOKEN}"
}
}
],
"defaultTimeout": 5000,
"defaultRetryCount": 2,
"maxConcurrentFetches": 10
}
5.2 Health-check
- Interval: Elke 30 seconden per gateway.
- Endpoint:
/api/v0/id (IPFS-standaard).
- Bij falen: Gateway uit allowlist verwijderen (tijdelijk). Bij herstel: terugvoegen.
- Logging: Elke health-check wordt gelogd met response-tijd en status.
6. Service Worker integratie
6.1 SW-registratie
// In shell (main-thread)
navigator.serviceWorker.register('/sw-ipfs.js', { scope: '/' })
.then(reg => {
// SW is actief voor alle fetch-verzoeken
console.log('IPFS SW geregistreerd');
});
// SW: sw-ipfs.js
self.addEventListener('fetch', event => {
const url = new URL(event.request.url);
// Alleen IPFS-verzoeken afvangen
if (url.pathname.startsWith('/ipfs/')) {
event.respondWith(verifiedFetch(url.pathname));
}
});
6.2 Verified-fetch implementatie
async function verifiedFetch(path) {
const cid = extractCID(path); // /ipfs/bafy... → bafy...
// 1. Check Helia-lokaal
const cached = await helia.get(cid);
if (cached) {
const verified = await verifyHash(cached, cid);
if (verified) return new Response(cached);
}
// 2. Gateway-allowlist
for (const gateway of allowlist) {
try {
const response = await fetch(gateway.url + path, {
signal: AbortSignal.timeout(gateway.timeout)
});
if (!response.ok) continue;
const bytes = new Uint8Array(await response.arrayBuffer());
// 3. Hash-verificatie
const verified = await verifyHash(bytes, cid);
if (!verified) {
auditLog('hash-mismatch', cid, gateway.name);
continue; // probeer volgende gateway
}
// 4. Cache voor volgende keer
await helia.pin(cid, bytes);
return new Response(bytes);
} catch (err) {
continue; // probeer volgende gateway
}
}
// 5. Alle gateways gefaald
return new Response('Content not available', { status: 503 });
}
7. Hash-verificatie detail
verifyHash(bytes, cid)
│
├── 1. CID parsen
│ ├── Multicodec: dag-pb of raw
│ ├── Multihash: SHA-256 (0x12)
│ └── Hash- bytes uit CID extraheren
│
├── 2. Hash berekenen
│ SHA-256(bytes) → berekende_hash
│
├── 3. Vergelijken
│ berekende_hash === verwachte_hash?
│ │
│ ├── Ja → return true (geldig)
│ └── Nee → return false (ongeldig)
│
└── 4. Bij false: audit-log
{
event: "hash-mismatch",
cid: "bafy...",
gateway: "kubo-primary",
timestamp: "2025-01-15T10:30:00Z",
expected: "0x1220...",
calculated: "0x1220..."
}
8. Acceptatiecriteria
| # | Criteria | Meting |
| AC-1 | Elke fetch wordt geverifieerd op hash-integriteit | Test met gemanipuleerde data: reject |
| AC-2 | Immutable CIDs worden oneindig gecachet | Test: tweede fetch = zero-network |
AC-3Mutable pointers (IPNS) worden na 5 minuten herverifieerd | Test: fetch na 6 min = opnieuw ophalen |
| AC-4 | Publieke gateways worden geweigerd | Test: fetch naar ipfs.io = error |
| AC-5 | Bij gateway-faal: fallback naar volgende private gateway | Test: Primary down → Replica |
| AC-6 | Bij alle gateways falen: 503 response (geen publieke fallback) | Test: alle gateways down = 503 |
| AC-7 | Hash-mismatch wordt gedetecteerd en gelogd | Test: gemanipuleerde data = audit-log |
9. Risico's en aanbevelingen
| Risico | Impact | Aanbeveling |
| Alle gateways falen gelijktijdig | hoog | Kubo Replica als tweede backup. Health-check detecteert falen snel. |
| Hash-mismatch door network-corruptie | middel | Bij mismatch: gateway uit allowlist + herhaal fetch bij alternatieve gateway. |
| IPNS-resolutie langzaam (>5s) | middel | IPNS-cache met 5 min TTL. Bij langzame resolutie: gebruik laatst bekende CID. |
| Helia-cache loopt vol (geheugendruk) | middel | LRU-evictie + emergency cleanup bij geheugendruk. |
| Gateway-wijziging niet opgemerkt | laag | Health-check elke 30s. Bij wijziging: automatische verwijdering uit allowlist. |
10. Verwijzingen naar verwante specs
Volgende stap Na akkoord: SW implementatie (verified-fetch + cache) + Gateway Router + Hash Verifier + Helia-integratie + Gateway-allowlist config.
11. Grillvragen
- Vraag 1: Moet de SW ook een "stale-while-revalidate" strategie ondersteunen voor mutable content, of is de harde 5-minuten TTL voldoende?
- Vraag 2: Hoe wordt de Gateway-allowlist gesynchroniseerd tussen Kubo-nodes: via een signed config, of via IPNS-self-pinning?
- Vraag 3: Wat is het gedrag als een pinned CID niet meer beschikbaar is bij een provider: direct herpin bij alternatieve provider, of wachten op dagelijkse verificatie?
|