OASIS Learn/Module 9
Intermediate ⏱ 35 min WEB4

HyperDrive Storage — Deep Dive

HyperDrive is the storage engine under every Holon and file in the OASIS. It abstracts dozens of storage providers behind a single API, handles auto-failover and auto-replication invisibly, and gives your app a real-time health dashboard to monitor it all.

What you'll learn

  • How HyperDrive sits between your app and every storage provider
  • Upload and download binary files (images, PDFs, game assets)
  • Read the live HyperDrive dashboard — provider health, latency, throughput
  • Trigger manual failover and inspect replication state
  • Tune auto-failover thresholds in OASISDNA.json
  • Use the Files API for structured file metadata alongside binary storage
📦
npm package

All examples use @oasisomniverse/web4-api. Install with npm install @oasisomniverse/web4-api. Full API reference: HyperDrive-API.md ↗ and Files-API.md ↗.

How HyperDrive Works

When your app calls saveFile() or saveHolon(), HyperDrive intercepts the request and fans it out across your configured providers. Reads are served from whichever provider responds first. Writes go to all providers simultaneously when auto-replication is on.

Architecture overview
Your App
    │
    ▼  @oasisomniverse/web4-api
OASIS ONODE (WEB4 API)
    │
    ▼  HyperDrive Engine
┌───────────────────────────────────────┐
│  MongoDBOASIS  HoloOASIS  IPFSOASIS   │
│  SolanaOASIS   Neo4jOASIS SQLLiteOASIS│
│  ThreeFoldOASIS  AzureCosmosOASIS …  │
└───────────────────────────────────────┘
         auto-failover / auto-replication

Uploading Files

Use oasis.files.saveFile() to upload binary data. The file is stored on HyperDrive and replicated to all active providers. The response includes a fileId you use to retrieve it later.

upload.js
import { oasis } from './oasis.js';
import { readFileSync } from 'fs';

const { avatarId } = oasis.auth.getSession();

// Read a local file
const bytes = readFileSync('./avatar-portrait.png');

const { result: file, isError } = await oasis.files.saveFile({
  avatarId,
  fileName:    'avatar-portrait.png',
  mimeType:    'image/png',
  description: 'Player portrait',
  fileData:    bytes.toString('base64'),   // base64-encode the bytes
  tags:        ['avatar', 'portrait'],
});

if (!isError) {
  console.log('Uploaded → fileId:', file.id);
  console.log('Providers replicated:', file.replicatedProviders);
}

Downloading Files

download.js
const { result: file } = await oasis.files.loadFile({ fileId: file.id });

// fileData is base64-encoded bytes
const buf = Buffer.from(file.fileData, 'base64');
writeFileSync('./downloaded-portrait.png', buf);
console.log('Downloaded', buf.length, 'bytes from provider:', file.servedFromProvider);

The HyperDrive Dashboard

The dashboard endpoint gives you a real-time snapshot of every provider's health — latency, throughput, error rate, and replication lag. Use it to build status pages, alerting, or in-app health indicators like the OPORTAL status bar.

dashboard.js
const { result: dash } = await oasis.hyperDrive.getDashboard();

console.log('Active providers:', dash.activeProviders);
console.log('Overall health:', dash.overallHealth); // "Healthy" | "Degraded" | "Critical"

for (const p of dash.providerMetrics) {
  console.log(`  ${p.providerType}: latency=${p.avgLatencyMs}ms  errors=${p.errorRate}%`);
}

// Active alerts (failover events, quota warnings…)
for (const alert of dash.alerts) {
  console.log('⚠️  Alert:', alert.message, 'severity:', alert.severity);
}
💡
Poll the dashboard for a live status bar

Poll getDashboard() every 30 seconds and update a status indicator in your UI. OPORTAL and the SovereignTrust site both use this pattern. See also HyperDrive-API.md ↗ for the full response schema.

Provider Metrics & Performance

metrics.js
const { result: metrics } = await oasis.hyperDrive.getMetrics();

// Aggregate across all providers
console.log('Total requests/sec:',  metrics.aggregate.requestsPerSec);
console.log('Bytes in/sec:',        metrics.aggregate.bytesReadPerSec);
console.log('Bytes out/sec:',       metrics.aggregate.bytesWrittenPerSec);

// Per-provider breakdown
for (const [provider, m] of Object.entries(metrics.services)) {
  console.log(`  ${provider}  peers=${m.peersConnected}  latency=${m.avgLatencyMs}ms`);
}

Manual Failover & Provider Switching

HyperDrive's auto-failover handles outages transparently. But you can also manually switch the active provider — useful for testing, migrations, or per-region routing.

failover.js
// Disable a provider (e.g. for maintenance)
await oasis.provider.disableProvider({ providerType: 'MongoDBOASIS' });

// HyperDrive will immediately route reads/writes to the next priority provider
// Re-enable when ready
await oasis.provider.enableProvider({ providerType: 'MongoDBOASIS' });

// Change provider priority
await oasis.provider.setProviderPriority({ providerType: 'HoloOASIS', priority: 1 });

Tuning Auto-Failover in OASISDNA.json

The ONODE reads failover thresholds from OASISDNA.json. Adjust these to match your SLA requirements:

OASISDNA.json (relevant excerpt)
{
  "OASISDNA": {
    "HyperDrive": {
      "AutoFailOver":              true,
      "AutoReplication":           true,
      "AutoLoadBalance":           true,
      "FailOverRetryAttempts":     3,
      "FailOverRetryIntervalMs":   2000,
      "FailOverMaxLatencyMs":      5000,
      "ReplicationIntervalMs":     30000
    }
  }
}
⚠️
Auto-replication vs auto-failover

Auto-replication writes data to every configured provider. Auto-failover silently retries failed reads/writes on the next provider. You can enable both independently — but if you enable auto-replication without auto-failover, a single provider going down during a write will surface as an error.

Next steps