@evolu/relay 1.1.2-preview.5 → 4.0.0

package/README.md

@@ -1,91 +1,64 @@
 # Evolu Relay
 
-A WebSocket relay server for the Evolu database system that enables real-time synchronization between clients.
+Evolu Relay provides sync and backup for Evolu apps. This package is the
+reference relay built on Node.js. It is published to npm as `@evolu/relay` and
+to Docker Hub as [`evoluhq/relay`](https://hub.docker.com/r/evoluhq/relay).
 
-## 🚀 Quick Start
+The relay listens on port 4000 by default and stores its SQLite database in
+the `data` directory of the current working directory. Point your app to
+`ws://localhost:4000` by setting the WebSocket transport in your Evolu config.
 
-### Docker Development (Recommended)
+## Run with npm
 
 ```bash
-cd apps/relay
-pnpm docker:up
+npx @evolu/relay
 ```
 
-### Production Deployment
+## Run with Docker
 
 ```bash
-# Complete server setup + deployment
-pnpm deploy:full
+docker run --rm -p 4000:4000 -v evolu-relay-data:/app/data docker.io/evoluhq/relay:4
 ```
 
-The relay will be available at `http://localhost:4000` (Docker) or your server's IP:4000 (production)
+For Docker Compose, download the repository's
+[`docker-compose.yml`](https://github.com/evoluhq/evolu/blob/main/apps/relay/docker-compose.yml)
+and run `docker compose up` from the directory containing that file.
 
-## 📖 Documentation
+Tags follow the npm package version: `4.0.0`, `4.0`, `4`, and `latest` for the
+newest stable release. Prerelease versions only get their full version tag.
 
-- **[Docker Setup](./README.docker.md)** - Complete Docker containerization guide
+## Configure
 
-## 🔧 Development
+The relay reads `PORT` and Relay-specific `EVOLU_RELAY_*` environment variables:
 
-### Local Development (Node.js)
+| Variable                      | Default  | Description                                                     |
+| ----------------------------- | -------- | --------------------------------------------------------------- |
+| `PORT`                        | `4000`   | The TCP port to listen on, also supplied by hosting platforms.  |
+| `EVOLU_RELAY_MAX_OWNER_BYTES` | No limit | The storage quota per owner, as a size literal such as `10MiB`. |
 
-```bash
-pnpm dev    # Start with file watching
-pnpm build  # Build TypeScript
-pnpm start  # Start built application
-```
+Quota values use `ByteSizeLiteral`, such as `0B`, `512KiB`, or `1.5GiB`.
+Bare byte counts such as `1048576` are not accepted; use `1MiB` instead.
+Leave the variable unset for no per-owner storage limit, or set a quota
+appropriate for your deployment. `0B` allows no stored bytes; it does not disable
+the quota. A per-owner quota is not a limit on total disk usage.
 
-### Docker Development
+An invalid `PORT`, or an empty, malformed, or unknown `EVOLU_RELAY_*` variable,
+stops the relay with a formatted validation error. Invalid supplied values
+never fall back to defaults. `EVOLU_RELAY_PORT` is not supported; use `PORT`.
 
 ```bash
-pnpm docker:up           # Start with logs
-pnpm docker:up:detached  # Start in background
-pnpm docker:down         # Stop containers
-pnpm docker:logs         # View logs
-pnpm docker:shell        # Access container shell
-pnpm docker:clean        # Clean up everything
+PORT=4001 EVOLU_RELAY_MAX_OWNER_BYTES=10MiB npx @evolu/relay
 ```
 
-## 🛠️ Available Commands
-
-### Development
-
-| Command      | Description                                 |
-| ------------ | ------------------------------------------- |
-| `pnpm dev`   | Start development server with file watching |
-| `pnpm build` | Build TypeScript to JavaScript              |
-| `pnpm start` | Start the built application                 |
-| `pnpm clean` | Clean build artifacts                       |
-
-### Docker
-
-| Command                   | Description                          |
-| ------------------------- | ------------------------------------ |
-| `pnpm docker:up`          | Build and start containers with logs |
-| `pnpm docker:up:detached` | Start containers in background       |
-| `pnpm docker:down`        | Stop all containers                  |
-| `pnpm docker:restart`     | Restart containers with rebuild      |
-| `pnpm docker:logs`        | View container logs                  |
-| `pnpm docker:shell`       | Access running container shell       |
-| `pnpm docker:stats`       | View container resource usage        |
-| `pnpm docker:clean`       | Remove containers and cleanup        |
-
-## 📋 Requirements
-
-- **Node.js** ≥22.0.0
-- **Docker** (for containerized development/deployment)
-- **pnpm** (workspace package manager)
+The Docker health check follows `PORT`. Use a fixed, nonzero port in Docker;
+`PORT=0` selects an unpredictable port that the health check cannot discover.
+The image exposes port 4000, so map a custom port explicitly:
 
-## 🔗 Integration
-
-After deployment, your Evolu applications can connect to the relay:
-
-**Development**: `ws://localhost:4000`  
-**Production**: `ws://your-server-ip:4000`
-
-The relay handles WebSocket connections and data synchronization across all connected Evolu applications.
-
----
-
-📚 **Quick Links**:
+```bash
+docker run --rm -e PORT=4001 -p 4001:4001 -v evolu-relay-data:/app/data docker.io/evoluhq/relay:4
+```
 
-- [Docker Setup Guide](./README.docker.md) - Local development and testing
+To add authorization or integrate the relay into your own server, use the
+`createRelay` API from `@evolu/nodejs` instead. This package's
+[`src/index.ts`](https://github.com/evoluhq/evolu/blob/main/apps/relay/src/index.ts)
+is the complete example.

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/index.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { ByteSizeLiteral, byteSizeToByteLength, createConsole, createConsoleFormatter, env, optional, Port, PortFromString, withDefault, } from "@evolu/common";
+import { installPolyfills } from "@evolu/common/polyfills";
+import { createRelay, createRelayDeps, runMain } from "@evolu/nodejs";
+import { mkdirSync } from "node:fs";
+installPolyfills();
+/** Validated hosting and Evolu Relay environment settings. */
+const RelayEnv = env({
+    port: withDefault(optional(PortFromString), Port.orThrow(4000)),
+    EVOLU_RELAY: {
+        maxOwnerBytes: optional(ByteSizeLiteral),
+    },
+});
+const deps = {
+    ...createRelayDeps(),
+    console: createConsole({
+        // level: "debug",
+        formatter: createConsoleFormatter()({
+            timestampFormat: "relative",
+        }),
+    }),
+};
+await runMain(deps)((run) => {
+    const config = RelayEnv.orThrow(process.env, { errors: "all" });
+    const maxOwnerBytes = config.maxOwnerBytes === undefined
+        ? undefined
+        : byteSizeToByteLength(config.maxOwnerBytes);
+    // Ensure the database is created in a predictable location for Docker.
+    mkdirSync("data", { recursive: true });
+    process.chdir("data");
+    return run(createRelay({
+        port: config.port,
+        // Note: Relay requires URL in format ws://host:port/<ownerId>
+        // isOwnerAllowed: (_ownerId) => true,
+        isOwnerWithinQuota: (_ownerId, requiredBytes) => maxOwnerBytes === undefined || requiredBytes <= maxOwnerBytes,
+    }));
+});

package/package.json

@@ -1,41 +1,49 @@
 {
   "name": "@evolu/relay",
-  "version": "1.1.2-preview.5",
+  "version": "4.0.0",
+  "description": "Evolu Relay server",
+  "keywords": [
+    "evolu",
+    "local-first",
+    "relay",
+    "sync"
+  ],
+  "author": "Daniel Steigerwald <daniel@steigerwald.cz>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evoluhq/evolu.git"
+  },
+  "bugs": {
+    "url": "https://github.com/evoluhq/evolu/issues"
+  },
+  "homepage": "https://evolu.dev",
   "type": "module",
   "bin": {
-    "@evolu/relay": "dist/src/cli.js"
+    "evolu-relay": "./dist/src/index.js"
   },
+  "files": [
+    "dist/src/**",
+    "README.md"
+  ],
   "dependencies": {
-    "commander": "^14.0.1",
-    "@evolu/common": "6.0.1-preview.19",
-    "@evolu/nodejs": "1.0.1-preview.7"
+    "@evolu/common": "8.10.0",
+    "@evolu/nodejs": "4.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.17.1",
-    "typescript": "^5.9.2",
-    "@evolu/tsconfig": "0.0.2"
+    "@evolu/typescript-config": "0.1.1",
+    "@types/node": "^24.10.9",
+    "@typescript/native": "npm:typescript@^7.0.2"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.20.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "dev": "tsx --watch src/cli.ts -- start",
-    "build": "shx rm -rf dist && tsc",
-    "start": "node dist/src/cli.js",
-    "clean": "shx rm -rf .turbo node_modules dist db.sqlite",
-    "docker:build": "docker-compose build --no-cache",
-    "docker:up": "docker-compose up --build",
-    "docker:up:detached": "docker-compose up -d --build",
-    "docker:down": "docker-compose down -v",
-    "docker:restart": "docker-compose down && docker-compose up --build",
-    "docker:logs": "docker-compose logs -f evolu-relay",
-    "docker:shell": "docker exec -it evolu-relay-server sh",
-    "docker:inspect": "docker inspect evolu-relay-server",
-    "docker:stats": "docker stats evolu-relay-server",
-    "docker:clean": "docker-compose down -v && docker system prune -f",
-    "docker:clean:all": "docker-compose down -v && docker system prune -af && docker volume prune -f"
+    "dev": "node --watch --watch-preserve-output src/index.ts",
+    "build": "tsc --build tsconfig.json",
+    "start": "node dist/src/index.js"
   }
 }

package/.dockerignore

@@ -1,16 +0,0 @@
-node_modules
-.turbo
-dist
-*.log
-.env
-.env.local
-.DS_Store
-coverage
-.nyc_output
-*.db
-*.sqlite
-.git
-.gitignore
-README.md
-CHANGELOG.md 
-examples

package/.turbo/turbo-build.log

@@ -1,4 +0,0 @@
-
-> @evolu/relay@1.1.2-preview.5 build /home/runner/work/evolu/evolu/apps/relay
-> shx rm -rf dist && tsc
-