Sync

Private API

Every call is authenticated with a bearer token, sent as Authorization: Bearer <token>. There is nothing else to the surface. There is no dashboard, login, session or cookie. The file routes are versioned under /api/v2 (API_VERSION = 2); the local scripts pins the prefix to its own version, so a server on a different version answers 426 Upgrade Required rather than silently following the local scripts onto a contract it does not speak. On such a skew the local scripts reads the unversioned GET /api/version, which reports the server's version, and says which side to upgrade.

With a valid token the HTTP status line carries the outcome: 200 ok, 400 a bad path, 410 the path is absent (normal descent, the local scripts then creates it), 500 a failed write, and 426 a request on a different API version's path. Without a valid token, or on an unknown route, every reply is an identical 404 <h1>Not Found</h1> wall, so an unauthenticated probe cannot tell the API is there at all (see Server).

GET /api/v2/tree

Returns the Merkle node at a path, so the local scripts can compare hashes and descend only into the subtrees that differ. A file node is its metadata hash; a directory node is the hash of its children, optionally with those children one level down. The tree is built by the server's manifest.js with skipUnderscore, so an entry whose name starts with _, and any dotted entry, never appears on either side and the two hashes agree. Every hash is derived from stat() alone, size and whole-second mtime, so the tree is built without reading any file contents.

GET /api/v2/tree?path=backup&depth=1 HTTP/1.1
Authorization: Bearer <token>

{
  "type": "dir",
  "hash": "b1946ac9…",
  "children": {
    "backup": { "type": "dir",  "hash": "9f86d081…" },
    "report":   { "type": "dir",  "hash": "3a7bd3e2…" }
  }
}

PUT /api/v2/file

Uploads one file, creating or overwriting it, and stamps it with the source mtime, so the metadata hash matches on both sides next run. The body streams straight to a hidden .chtmp-* temp file in the same directory and is renamed into place atomically, so a half-written file is never served and memory stays bounded regardless of file size.

PUT /api/v2/file?path=backup/cronhoster-cron-handler.js&mtime=1784514159000 HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/octet-stream

<file bytes>

{ "size": 1234, "mtime": 1784514159000 }

DELETE /api/v2/file

Removes a file, or a whole cron directory subtree, that exists on the server but is gone locally. A directory delete removes its subtree and then prunes any now-empty parent directories, since the server never stores empty directories. Deleting a path that is already absent is still a 200. The desired state is reached either way, so delete is idempotent.

DELETE /api/v2/file?path=report HTTP/1.1
Authorization: Bearer <token>

{ "deleted": true }

Synchronisation Process

A sync is a comparison of two Merkle trees built from file metadata; the local scripts only ever sends the differences. Each file's hash is sha256(size : mtime-seconds), derived from stat() alone, so building the tree reads no file data; a directory's hash is the hash of its sorted child name:hash lines. Two directories therefore share a hash only when every file beneath them has identical size and timestamp. The local scripts walks from the root, compares hashes, and descends only where they differ, so it transfers only the files the server does not already have. The tree builder is the same algorithm on both sides — the server's manifest.js and the local scripts' own copy — so the two sides can never disagree.

1. Resolve the API version. The local scripts builds the /api/v2 prefix from its own version. On an unexpected status it reads GET /api/version and reports which side to upgrade.
2. List the top-level names. GET /api/v2/tree?path=&depth=1 returns the server's top-level cron directories. The local scripts compares them by name with its own. If the root hash already matches, nothing changed and the run finishes in a single request.
3. Upload each new cron. For a name present locally but not on the server, the local scripts descends the local tree and PUTs every file in that cron directory, streamed with backpressure. The server applies the sent mtime so the hashes match next time.
4. Delete each removed name. For a name on the server but gone locally, DELETE removes the whole subtree. Deletes run first, so a type change is handled cleanly, then the uploads.

Errors

With a valid token, a failure is an HTTP status with a short { "error": … } body. Without one, every reply is the same 404 wall.