urlsv0.1.0-ffi
GitHubStatsDocs
Workspace/Documentation

API Reference & System Architecture

Integrate with the ultra-compact URL engine via HTTP REST or native C-ABI bindings.

BASE HOST

https://urls.aduki.pro

Edge Anycast Routing

INDEX FOOTPRINT

3.62 Bytes / Key

Minimal Perfect Hashing

LOOKUP LATENCY

3.06 µs (p50)

Zero-Copy Mmap

HTTP REST Endpoints

6 available routes
POST/api/shorten
Stateful Core

Compresses a long destination URL into a 5-character Base66 key and indexes it in sharded memory-mapped Bitcask logs.

Request Payload (JSON):
{
  "url": "https://github.com/rust-lang/rust"
}
Response:
{
  "key": "058qV",
  "url": "https://github.com/rust-lang/rust",
  "shortUrl": "https://urls.aduki.pro/058qV",
  "statelessCode": "058qV",
  "savedBytes": 5,
  "ratio": "84.8%"
}
GET/:key
Redirection

Resolves a 5-character shortcode directly to the original target URL using zero-copy memory-mapped slice reads.

Parameters:
:key → 5-char Base66 token
Header → standard User-Agent
Response:
HTTP/2 302 Found
Location: https://github.com/rust-lang/rust
Server: Fly.io
POST/api/batch
Streaming Batch

Ingests arrays of URLs in streaming chunks. Built for high-volume CSV, TSV, and TXT pipelines up to 100 MB.

Request Payload (JSON):
{
  "urls": [
    "https://github.com/rust-lang/rust",
    "https://news.ycombinator.com"
  ]
}
Response:
{
  "success": true,
  "count": 2,
  "durationMs": "1.42",
  "ratePerSec": 1408,
  "items": [
    {
      "url": "https://github.com/rust-lang/rust",
      "key": "058qV",
      "shortUrl": "https://urls.aduki.pro/058qV"
    }
  ],
  "stats": {
    "keys": 2,
    "ramBytes": 140,
    "diskBytes": 301,
    "bytesPerKey": 70.0
  }
}
POST/api/encode
Stateless Codec

Algorithmically encodes or decodes a URL using Myers positional deltas and dictionary tokenization with zero database lookups.

Request Payload (JSON):
{
  "input": "https://github.com/rust-lang/rust",
  "action": "encode"
}
Response:
{
  "result": "058qV",
  "action": "encode"
}
GET/api/stats
Telemetry

Returns live index metrics, total indexed key count, sealed RAM consumption, and on-disk payload size.

Parameters:
:key → 5-char Base66 token
Header → standard User-Agent
Response:
{
  "success": true,
  "keys": 4313006,
  "ramBytes": 15634432,
  "diskBytes": 748650496,
  "bytesPerKey": 3.62,
  "ramMb": "14.91",
  "diskMb": "713.97"
}
GET/health
Health Check

Fast, unauthenticated readiness probe for Kubernetes, Fly.io, and uptime monitoring.

Parameters:
:key → 5-char Base66 token
Header → standard User-Agent
Response:
{
  "status": "ok",
  "engine": "ready",
  "version": "0.1.0-ffi",
  "keys": 4313006,
  "ramBytes": 15634432,
  "diskBytes": 748650496,
  "bytesPerKey": 3.62
}

Direct Native C-ABI Integration (Zero Network Overhead)

For microsecond-latency applications in Node.js, Python, or Go, bind directly to native/liburls.so using standard FFI:

import koffi from "koffi";

const lib = koffi.load("native/liburls.so");
const shorten = lib.func("urls_shorten", "str", ["str", "str"]);
const expand = lib.func("urls_expand", "str", ["str", "str"]);

// 3.06 microsecond stateful lookup
const shortKey = shorten("https://github.com/rust-lang/rust", ".store");
const targetUrl = expand(shortKey, ".store");