Lioran S3 Documentation

300+ MB/s

Write Throughput

Benchmarked streaming uploads

300+ MB/s

Read Throughput

Benchmarked streaming downloads

100 GB

Tested Workload

Soak tested single-node datasets

* Benchmark results measured in controlled local and network environments. Actual throughput varies with hardware, storage media (NVMe vs SSD), object size distribution, concurrency, network topology, and configured write durability modes (strict vs balanced).

Command Line Workflow

Manage buckets, objects, resumable multipart uploads, and access keys directly from your terminal.

# 1. Install official CLI
npm install -g @liorans3/cli@prealpha

# 2. Configure connection profile (interactive or flag-based)
liorans3 configure --endpoint http://127.0.0.1:27118 --username admin -P admin

# 3. Create bucket and verify
liorans3 bucket create assets
liorans3 bucket ls

# 4. Upload object with bounded-memory streaming
liorans3 object put assets logo.png ./logo.png --content-type image/png

# 5. List objects and download
liorans3 object ls assets
liorans3 object get assets logo.png ./downloaded-logo.png

TypeScript & JavaScript Driver

Type-safe, bounded-memory client library with streaming I/O, cursor pagination, and automatic retries.

// Install driver: npm install @liorans3/driver
import { BastionClient } from '@liorans3/driver';
import * as fs from 'node:fs';

// Initialize client with connection URI
const client = new BastionClient('bastion://admin:YOUR_PASSWORD@127.0.0.1:27118');

// Target bucket
const bucket = client.bucket('assets');

// Upload streaming payload
const fileStream = fs.createReadStream('./dataset.tar.gz');
const meta = await bucket.put('archives/dataset.tar.gz', fileStream, {
  contentType: 'application/gzip',
});
console.log(`Uploaded ${meta.key} (ETag: ${meta.etag})`);

// Download object directly to disk
const object = await bucket.get('archives/dataset.tar.gz');
await object.writeToFile('./restored-dataset.tar.gz');

// Query paginated list
const page = await bucket.listPage({ prefix: 'archives/', limit: 50 });
console.log(`Found ${page.objects.length} items (has_more: ${page.has_more})`);

Engineered for Predictable Performance

A decoupled storage and metadata architecture designed to avoid memory bloat and locking contention.

Bounded-Memory Streaming

Uploads and downloads stream through fixed-size buffers (64 KiB – 4 MiB) between network sockets and disk descriptors. Objects are never buffered entirely in RAM.

Decoupled RocksDB Metadata

Transactional metadata, bucket quotas, and multipart sessions reside in an embedded RocksDB key-value store, completely separated from physical payload volumes.

Resumable Multipart Uploads

High-throughput parallel chunk ingestion with automatic retries, incremental checksum verification, and atomic commit semantics.

Crash Durability Guarantees

Configurable write durability with strict per-write physical disk sync (fsync) or balanced OS writeback caching.

Expiring Presigned URLs

Cryptographically signed HMAC-SHA256 URLs for delegated GET, PUT, and HEAD operations without leaking long-term credentials.

Identity & Access Keys

Role-based user management (admin, readwrite, readonly) and programmatic Access Key authentication with rotatable secrets.

Production Deployment

Deploy in minutes with Docker Compose, automatic HTTPS certificate provisioning via Caddy, and persistent volumes.

# docker-compose.yml
services:
  bastion:
    image: liorans3/liorans3:pre-alpha
    container_name: bastion-server
    restart: unless-stopped
    expose:
      - "27118"
    environment:
      - BASTION_ENV=production
      - BASTION_HOST=0.0.0.0
      - BASTION_PORT=27118
      - BASTION_DATA_DIR=/data
      - BASTION_ADMIN_PASSWORD=${BASTION_ADMIN_PASSWORD}
      - BASTION_SIGNING_SECRET=${BASTION_SIGNING_SECRET}
    volumes:
      - bastion-data:/data

  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    environment:
      - BASTION_DOMAIN=s3.example.com
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    depends_on:
      - bastion

volumes:
  bastion-data:
  caddy-data:
  caddy-config:

Build with Lioran S3

Explore the guides below to get started, integrate with the driver, or deploy to production.

Lioran S3