Repository navigation
Server API and Storage
roomcad/server/server.py is the whole backend: Python standard library only,
SQLite for storage, reverse-proxied by Caddy under /api/* and bound to
127.0.0.1:8078 so it is never exposed directly.
One shared password, checked server-side, supplied through the
ROOMCAD_PASSWORD environment variable (never in git). POST /api/login sets
an HttpOnly cookie; every other endpoint returns 401 without it. If the
password is not configured the service still starts, but logins fail closed.
# log in and keep the cookie
curl -s -c jar.txt -X POST localhost:8078/api/login \
-H 'Content-Type: application/json' -d '{"password":"letmein"}'
# {"ok": true}
# every later call reuses it
curl -s -b jar.txt localhost:8078/api/roomsOnly a SHA-256 hash of the session token is stored, never the token.
| Method | Path | Purpose |
|---|---|---|
POST |
/api/login |
exchange the password for a session cookie |
GET |
/api/rooms |
list rooms (latest version of each) |
GET |
/api/load/<name> |
load the latest version, or ?version=N
|
GET |
/api/versions/<name> |
list a room's versions, newest first |
POST |
/api/save |
save a new version → {name, version}
|
DELETE |
/api/rooms/<name> |
delete every version of a room |
GET |
/api/watch/<name> |
Server-Sent Events stream of updates |
POST |
/api/live/<name> |
publish an unsaved live draft |
GET |
/api/session/last |
the design this browser should reopen |
POST |
/api/session/last |
remember a design for this browser |
GET |
/api/status |
{"count": N} — sessions active in the last 30 s |
Names are sanitised to [A-Za-z0-9_-]. Saving with an empty name allocates the
next free ternak_roomN inside the same lock as the insert, so two
simultaneous saves can never collide.
# save a design (empty name = allocate a new slot)
curl -s -b jar.txt -X POST localhost:8078/api/save \
-H 'Content-Type: application/json' \
-d '{"name":"","json":"{\"format\":\"com.maria.roomcad-v2.room\",...}","clientId":"cli"}'
# {"name": "ternak_room4", "version": 1}
# list the versions of that room
curl -s -b jar.txt localhost:8078/api/versions/ternak_room4
# [{"version": 1, "savedAt": 1755900000000}]
# fetch one exact version
curl -s -b jar.txt 'localhost:8078/api/load/ternak_room4?version=1'
# follow live updates (stays open, one JSON object per event)
curl -sN -b jar.txt localhost:8078/api/watch/ternak_room4CREATE TABLE rooms (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
version INTEGER NOT NULL,
json TEXT NOT NULL,
saved_at INTEGER NOT NULL, -- epoch ms
client_id TEXT,
UNIQUE(name, version)
);
CREATE TABLE browser_sessions (
token_hash TEXT PRIMARY KEY, -- sha256 of the cookie value
last_room_name TEXT,
last_room_version INTEGER,
created_at INTEGER NOT NULL,
expires_at INTEGER NOT NULL
);-
WAL mode,
synchronous=NORMAL,busy_timeout=5000— concurrent readers never block the writer, and a busy save retries instead of failing. - One connection is shared across request threads (
check_same_thread=False) and every statement is serialised behind a single lock. - On first boot, legacy
.rcadfiles inrooms/are imported as version 1 and removed.
POST /api/save always inserts version = max(version) + 1. Nothing is
ever overwritten, so any earlier state can be reopened from the version list.
GET /api/session/last answers it:
- If this browser has a remembered room and that exact version still exists → return it.
- Otherwise → return the project's most recently saved design, and remember it
for this browser (flagged
projectLatest: true). - If the project has no saved rooms at all →
null, and the app opens the built-in demo.
This lives in SQLite rather than local storage, so it survives an API restart and needs no second cookie.
POST /api/live/<name> keeps the newest unsaved draft per room in memory only
and pushes it to every watcher with "live": true. A real save clears it. They
are lost on restart, which is fine — they are drafts. See
Live Collaboration.