Skip to main content

Build a connector

A connector, or bridge, is a small program next to your own system. It pulls your account's workflow results from Constellation and writes what workflows forecast into your system. You write one function that writes a run's items, and one that carries out an approved action. The constellation command line tool scaffolds the rest, gives you a mock API to develop against, and checks your bridge before it goes live.

constellation bridge new ──▶ my-mcs/ (bridge, connector.json, test, Dockerfile)
constellation mock ──▶ stand-in results on localhost:7070, every action state in it
constellation conformance ──▶ runs your bridge, kills it, restarts it, judges what it did
constellation login ──▶ stores your API key
run it ──▶ checks in, you approve it, workflows send it results

You need an API key with predictions:read from the Keys page, and the Operator plan to deliver to your own connector. Your own connector is the full reference: the manifest, approval, what apply() receives and the rules for what you write.

1. Install the CLI and the SDK​

Download the constellation binary for your machine (Linux or macOS, amd64 or arm64), with SHA256SUMS and SHA256SUMS.sigstore.json, from the connectors releases (see Downloads), and check them with constellation verify, which needs cosign:

VERSION=vX.Y.Z # the release you use
CLI="constellation-$(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"
mkdir -p "constellation-$VERSION" && cd "constellation-$VERSION"
for f in "$CLI" SHA256SUMS SHA256SUMS.sigstore.json; do
curl -fsSLO "https://github.com/constellationhq/connectors/releases/download/$VERSION/$f"
done
chmod +x "$CLI" && "./$CLI" verify .
sudo cp "$CLI" /usr/local/bin/constellation
constellation version

See The constellation CLI for every command.

2. Scaffold a bridge​

constellation bridge new my-mcs --lang python
cd my-mcs
pip install --require-hashes -r requirements.txt

You get bridge.py, connector.json, test_bridge.py, requirements.txt, Dockerfile and a README.md. Python 3.11 or newer. requirements.txt pins constellation-space, the version released with the CLI, by its sha256, so no other upload of that name can install.

The name is your connection's name: lowercase letters, digits and -, at most 63 characters. Add --dir DIR to write somewhere other than ./my-mcs.

3. Write apply and act​

The scaffold already runs: it prints what it would write. Replace the prints with calls to your system.

from pathlib import Path

from constellation_space.bridges.template import Bridge


class MyMcs(Bridge):
def apply(self, items, settings, run):
"""Write one run's items into your system, keyed on item["entity"]["id"]."""
kept = [i for i in items if (i.get("value") or {}).get("p10", 0) >= settings.get("min_p10_gb", 0)]
for item in kept:
my_system.propose(item["entity"]["id"], item["target_at"], label=settings["label"])
return {"passes": len(kept)}

def act(self, item, settings, run):
"""Carry out one approved action; return True once done."""
action = item["action"]
my_system.swap(action["from"], action["to"])
return True


if __name__ == "__main__":
MyMcs(Path(__file__).with_name("connector.json")).run_forever()
  • apply(items, settings, run) gets every item of one run for your connection, the settings the workflow set from your manifest, and the run (workflow, version, run id and the window it answers for). Return what you wrote, such as {"passes": 12}: the workflow builder shows it.
  • act(item, settings, run) gets one approved action, after apply() has written the run. Return true once your system has carried it out.
  • Raise or return an error when your system is unreachable: the run is retried on the next poll and the cursor does not move past it.

Everything else is the base class: check-in (again every 5 minutes), pulling results as your connection, joining a paged run, skipping item shapes it was not built for, reporting each run, keeping the cursor, and stopping with a clear message when the key or plan is refused.

Safety rules​

The base class enforces these in every language. Conformance checks each one.

RuleWhat it means
Act only on approvedact() is called only for an item whose action state is approved. Advice, held (pending) and rejected actions, and plain forecasts, are written by apply() and never acted on.
Once per approvalEach approval is carried out once, even when a later run carries it again. The bridge remembers what it acted on by the result's decision_id, or, on a result without one, by entity.id|verb|to (the same verb on the same entity to the same target). A standing approval keeps its decision_id in every run, so it is acted on once; a new approval of an action acted on before has a new decision_id, so it is acted on again.
Unknown status is heldAn action_status the bridge does not know is read as pending, never as approved and never as a plain forecast.
Never past the deadlineAn approved action whose cancel deadline has passed is closed and never acted on.
Restart never re-actsWhat the bridge acted on is kept beside the cursor (CURSOR_FILE plus .acted), so a restarted bridge resumes from its cursor and does not act again. Each remembered key is kept 7 days past the latest of the item's target_at, until, the action's deadline and the time it acted, so a key is never dropped while a run can still send it. Keep both files on a volume.
Each run onceA run is applied once: a failed report is retried without writing or acting again, and a run a replaying feed delivers again, older than the cursor, is skipped.
Newest run firstA first start, with no cursor, begins at the feed's newest run with something for this connection, so a new bridge never applies or acts on older decisions. BACKFILL=1 applies the whole history the feed holds instead.

A run is the whole answer for its window, so withdraw what you wrote earlier for the same workflow inside the window that items no longer carries. Key everything you write on entity.id, so a rerun updates in place.

4. Run it against the mock API​

constellation mock

The mock serves the results endpoints on http://127.0.0.1:7070 with the same paths, cursors and JSON as the API. It replays the demo fleet: NOAA-20 passes over a ground station, a run in an item shape newer than bridges read, and Ka-band rain-fade swap runs with an action in every state, including a status no bridge knows, a standing approval sent again with the same decision_id, and a new approval of an action approved before. It accepts any x-api-key and needs none.

In another terminal:

CONSTELLATION_API_URL=http://127.0.0.1:7070 python bridge.py

5. Pass conformance​

constellation conformance -- python bridge.py

Conformance starts its own mock on a free port and runs your command with CONSTELLATION_API_URL, CONSTELLATION_API_KEY, a temporary CURSOR_FILE, POLL_SECONDS=1 and CONSTELLATION_CONFORMANCE_LOG set. It answers the first poll with 503, lets the bridge catch up, kills it, publishes more runs, and starts it again. Point the bridge at a test instance of your system: apply() and act() really run.

PASS checks in as a custom connector with a valid manifest
PASS checks in with consumer equal to the manifest's name
...
PASS keeps running until it is stopped
conformant

It exits 0 when every check passes, 1 when one fails, and 2 when it could not run (no command, a taken port, a command that does not start). --json prints the result as JSON for CI.

What conformance checks​

#Check
1Checks in as a custom connector with a valid manifest
2Checks in with consumer equal to the manifest's name
3Pulls its results as its own connection
4Keeps polling after the first poll is answered 503
5Consumes every forecast run and reports it applied
6Names its consumer, the run, the cursor and what it applied (up to 20 whole-number counts) in each report
7Never reports a run in an item shape it was not built for
8Applies each run once: one the feed delivers again (a replay from an older cursor) is skipped
9Reads on through a replay: it follows the replayed runs' cursors, never stops at the first
10Starts at the newest run on a first start, never the older history
11Reads every page of a paged run before it reports the run applied
12Moves past the last run it applied
13Writes the conformance log as JSON lines {item_id, state, acted, verb}
14Reads each item's action state as the API gives it (an unknown status is pending)
15Acts on each approved action exactly once
16Acts on a new approval of an action it acted on before, never again on a standing one
17Never acts on advice, pending, rejected or unknown-status actions, nor on plain forecasts
18Never acts on an action past its cancel deadline
19Resumes from its cursor after a restart
20Does not act again after a restart on what it acted on before
21Keeps running until it is stopped

Check 11 runs when the bridge asks for runs in pages, as the base classes do. A bridge for a built-in system, such as Yamcs, checks in as that system, and checks 1 and 2 become one: it checks in with a consumer.

The conformance log​

When CONSTELLATION_CONFORMANCE_LOG names a file, the bridge appends one JSON line per item it applies, after the run is applied and reported and before the cursor is saved. The base classes do this for you; a bridge written from scratch must write it to pass.

{"item_id": "pass_8f3a1c92d4e7", "state": "forecast", "acted": false, "verb": null}
{"item_id": "pass_51a0e7c2b9d3", "state": "advice", "acted": false, "verb": "swap"}
{"item_id": "pass_6d2f18a4c0e7", "state": "pending", "acted": false, "verb": null}
{"item_id": "pass_a7c3e5091f62", "state": "approved", "acted": true, "verb": "swap"}
FieldValue
item_idThe item's entity.id
stateforecast (no action), advice, approved, pending or rejected. An unknown action_status is pending.
actedtrue only for an approved action carried out just then. false for everything else, and for an approval already carried out.
verbThe action's verb, or null for an item with no action

No other fields. Unset, nothing is written.

6. Log in and run it​

constellation login # asks for the key, checks it, stores it

Run the bridge with your key. The scaffolds read CONSTELLATION_API_KEY; constellation login stores the key for the CLI's own commands, bound to the API it was stored for (see login).

CONSTELLATION_API_KEY=<a key with predictions:read> python bridge.py

On start it checks in. Approve it in the workflow builder, add it as an output to a workflow, and run the workflow. constellation results tail --consumer my-mcs shows the results sent to it. Each scaffold has a Dockerfile; keep CURSOR_FILE on a volume so a rebuilt container resumes and never acts twice.