RASLer

RASLer is a HTTP server that implements RASL's /.well-known/rasl/ endpoint, backed by content-addressed storage, MASL metadata support, and a full-featured operator API.

Features

• Storage — content blobs are stored by CID on disk, backed by a SQLite database that enables capacity management and a pluggable eviction policy
• DASL & MASL CIDs — content serving by simple DASL CIDs, or via MASL CIDs with path-based resolution for both single files and website bundles as per the proposed specification (see "RASL Path Resolution via MASL")
• Static roots — serve files from local directories by CID without copying them into the blob store
• Mount points - use human-friendly URLs with virtual hosts and MASL paths
• Operator API — upload raw files or CARs, pin/unpin, and evict; manage mount points; status, etc.
• Server factory — compose your own server including RASL functionality

Quick start

npm install
cp .env.example .env
# edit .env and set API_SECRET
cp rasler.config.example.json rasler.config.json  # optional — configure static roots, mount points, CORS
npm start
# open http://localhost:3000/api-docs in a browser

From the API docs UI, you can:

• Enter API_SECRET to authenticate
• Upload one or more files (or CARs with MASL metadata, see Utilities for help building) and record their MASL CIDs

Once uploaded, you can access the files at http://localhost:3000/.well-known/rasl/<cid>/.

Slow start

See USE_CASES for an overview of common deployment patterns including virtual hosting and static roots.

Configuration

Environment variables (.env)

| Variable | Required | Default | Description | |---|---|---|---| | ORIGIN | No | http://localhost:<PORT> | This node's public origin, protocol included (e.g. https://node1.example.com). Used in Link: rel="duplicate" headers. A bare hostname without protocol is accepted and defaults to https://. | | API_SECRET | Yes | — | Pre-shared secret to send as x-rasl-operator-secret header | | PORT | No | 3000 | HTTP listen port | | DATA_DIR | No | ./data | Directory for the SQLite database and content blobs | | TOTAL_CAPACITY | No | 1G | Storage budget (200M, 1G, 2GB, plain bytes) | | OPERATOR_API_PATH_PREFIX | No | — | Mount operator API under a path prefix (e.g. /admin) | | SWAGGER_UI | No | true | Set false to disable the interactive API docs at <operator-api-path-prefix>/api-docs |

rasler.config.json

Static roots, mount points, and CORS origins are configured in an optional rasler.config.json file in the working directory. Copy rasler.config.example.json to get started.

{
  "staticRoots": [
    { "path": "/var/www/assets", "watch": true, "ignore": ["**/*.log", ".DS_Store"] }
  ],
  "mountPoints": [
    { "hostname": "example.com", "directory": "/var/www/html" },
    { "hostname": "example.com", "prefix": "/docs", "directory": "/var/www/docs" }
  ],
  "operatorCorsOrigins": ["http://localhost:5173", "https://admin.example.com"]
}

| Key | Description | |---|---| | staticRoots | Directories to serve as static RASL roots. String entries use defaults; object entries add watch (re-index on change) and ignore (glob patterns to skip). See STATIC_ROOTS. | | staticMaxHistory | Maximum pinned MASL versions per static root; older versions are unpinned for LRU eviction. Omit for unlimited. | | mountPoints | Virtual host mappings: { hostname, prefix?, directory }. See MOUNT_POINTS. | | operatorCorsOrigins | Origins allowed to call the Operator API cross-origin. |

Implicit ./public mount — if a ./public directory exists and no root-level mount point is configured for the origin domain, RASLer automatically serves it at the document root with Link: rel="duplicate" headers.

API

RASL retrieval (public)

| Method | Path | Description | |---|---|---| | GET | /.well-known/rasl/:cid | Retrieve raw content by CID | | HEAD | /.well-known/rasl/:cid | Same as GET, no body | | GET | /.well-known/rasl/:cid/* | Retrieve content via MASL document CID; path suffix resolved against MASL resources | | HEAD | /.well-known/rasl/:cid/* | Same as GET, no body |

Operator API (requires x-rasl-operator-secret header)

| Method | Path | Description | |---|---|---| | GET | /status | Show server status (including storage usage) | | POST | /upload | Upload files (multipart or CAR) | | POST | /pin | Pin CIDs | | DELETE | /pin/:cid | Unpin a CID | | GET | /content | List held content | | GET | /content/:cid | Get content metadata | | DELETE | /content/:cid | Evict a CID | | GET | /static-roots | List configured static roots and their current MASL CIDs | | GET | /mount-points | List all mount points (static and runtime) with their MASL CIDs | | PUT | /mount-points/:hostname[/:prefix] | Map a hostname (with optional path prefix) to a held bundle MASL CID (runtime, persisted) | | DELETE | /mount-points/:hostname[/:prefix] | Remove a runtime mount point mapping |

The Operator API can be relocated via the OPERATOR_API_PATH_PREFIX environment option.

Full request/response details are in openapi.json and can be viewed and used interactively if SWAGGER_UI=true.

Utilities

The following utility script is included.

# Build a CAR file (with MASL bundle header) from a static website directory tree
npm run get-in-the-car <input-dir> [output.car]

Development

Contributions are welcome! Please use GitHub Issues to discuss or propose improvements or file bugs.

See ARCHITECTURE for a code walkthrough as well as details on using RASLer as a library.

Pull requests that make changes to the API should include updated JSDoc and a freshly generated openapi.json.

Scripts

# Run the node
npm start

# Run tests (includes lint)
npm test

# Lint only
npm run lint

# Regenerate openapi.json from JSDoc in src/routes/operator.js
npm run generate:openapi

# Generate HTML docs from *.md files into ./public
npm run generate:docs