Skip to content
CEagle

Keeping a calculator current

One request answers what the registry currently holds for up to 32 addresses, so a client can reconcile a whole calculator at once.

GET/api/v1/programs/versionsPublic

Send the addresses a calculator holds, get back what the registry has for each.

curl -s "https://roost.ceagle.cc/api/v1/programs/versions?slugs=snake,demo-library,usb-driver"
{
  "programs": [
    {
      "slug": "snake",
      "title": "Snake",
      "version": "1.2.0",
      "checksum": "3f9a…",
      "size": 14208,
      "var_name": "SNAKE",
      "var_type": "program",
      "archived": false,
      "language": "asm",
      "dependencies": ["graphx-helpers"]
    },
    { "slug": "demo-library", "missing": true }
  ]
}

The rules#

slugscomma-separatedRequired

Up to 32 addresses. Anything past the limit is ignored rather than rejected.

orderpreserved

The answer comes back in the order you asked, so the two lists line up positionally.

missingboolean

An address with nothing published at it comes back with missing: true rather than being dropped, which is what keeps the lists aligned.

duplicatescollapsed

And addresses that are not valid are skipped silently.

Sending no addresses at all answers 400.

Reconciling#

  1. Collect what the calculator holds

    You need the address each installed variable came from. A client that installed through Roost should record it; there is nothing in the variable itself that carries it.

  2. Ask in batches of 32

    for batch in chunk(installed_slugs, 32):
    answer = GET /api/v1/programs/versions?slugs=join(batch)

  3. Compare checksums, not versions

    A version string is for people. The checksum is the thing that decides whether the bytes differ.

    if entry.missing:            # gone from the registry
    mark stale
elif entry.checksum != local_checksum:
    needs update
else:
    up to date

  4. Update what changed

    Each update is an ordinary install, so it resolves its own dependencies first. Do not assume the dependency list is unchanged: dependencies comes back here for exactly that reason.

Why checksums rather than versions#

Nothing enforces a version format, and nothing stops an author from publishing twice under one version string. A version is a label; the checksum is the identity of the bytes.

Missing is not always gone#

missing: true means the registry will not serve that address right now. That covers three different situations, and the response deliberately does not distinguish them:

Never existed

A typo, or an address that was never published.

Archived

The project was archived, so the program is suspended.

Hidden

Left out of listings and checks, though still downloadable at its address.

A client should treat all three the same way: keep the local copy, stop offering updates for it, and say so if the person asks.

CEagle documentation