Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

20.4 KB
Raw Blame
"""Deployment setup — registers Mattermost bridge with Switch after both are ready.

Runs as a short-lived container: an init container under docker-compose, and a
post-install/post-upgrade Helm hook on a cluster deployment, so it also runs
against live installations on every upgrade. Waits for Switch and
Mattermost to be healthy, bootstraps the Mattermost admin/team, then registers
the Mattermost bridge via the authorized Switch gateway API — logging in as the
seeded gateway admin first, since bridge administration is an admin action.
Finally it links the seeded Mattermost account to that admin, so the deployment
comes up knowing which chat account its owner is.
"""

import os
import sys
import time

import httpx

SWITCH_URL = os.environ["SWITCH_URL"]
GATEWAY_ADMIN_EMAIL = os.environ["GATEWAY_ADMIN_EMAIL"]
GATEWAY_ADMIN_PASSWORD = os.environ["GATEWAY_ADMIN_PASSWORD"]
MATTERMOST_URL = os.environ["MATTERMOST_URL"]
MATTERMOST_URL_FOR_SWITCH = os.environ.get(
    "MATTERMOST_URL_FOR_SWITCH", "http://localhost:8065"
)
# User-facing Mattermost URL (what people open in their client), used to build
# channel deeplinks. Differs from MATTERMOST_URL_FOR_SWITCH, which is the
# internal address Switch connects to. Optional — falls back to the internal URL.
MATTERMOST_PUBLIC_URL = os.environ.get("MATTERMOST_PUBLIC_URL")
# Where the Mattermost *server* reaches switch-core's callback listener, for the
# button presses it delivers by HTTP. A third address, unrelated to the two
# above: those are routes to Mattermost, this is the route back. Optional —
# without it cards carry no buttons and stay answerable by typing.
MATTERMOST_CALLBACK_BASE_URL = os.environ.get("MATTERMOST_CALLBACK_BASE_URL")
MATTERMOST_ADMIN_USER = os.environ["MATTERMOST_ADMIN_USER"]
MATTERMOST_ADMIN_PASSWORD = os.environ["MATTERMOST_ADMIN_PASSWORD"]
MATTERMOST_ADMIN_EMAIL = os.environ.get(
    "MATTERMOST_ADMIN_EMAIL", f"{os.environ['MATTERMOST_ADMIN_USER']}@localhost.local"
)
MATTERMOST_TEAM_NAME = os.environ["MATTERMOST_TEAM_NAME"]
MATTERMOST_USER = os.environ["MATTERMOST_USER"]
MATTERMOST_USER_PASSWORD = os.environ["MATTERMOST_USER_PASSWORD"]
MATTERMOST_USER_EMAIL = os.environ.get(
    "MATTERMOST_USER_EMAIL", f"{os.environ['MATTERMOST_USER']}@localhost.local"
)

MAX_RETRIES = 60
RETRY_DELAY = 5

# Shorter than MAX_RETRIES: by the time this runs both services have answered,
# so it waits only for the bridge adapter to finish starting.
LINK_MAX_RETRIES = 24


def wait_for_service(url: str, name: str) -> None:
    for attempt in range(1, MAX_RETRIES + 1):
        try:
            resp = httpx.get(url, timeout=5)
            if resp.is_success:
                print(f"{name} is ready")
                return
        except httpx.HTTPError:
            pass
        print(f"Waiting for {name} ({attempt}/{MAX_RETRIES})...")
        time.sleep(RETRY_DELAY)
    print(f"ERROR: {name} did not become ready after {MAX_RETRIES} attempts")
    sys.exit(1)


def setup_mattermost() -> str | None:
    """Create admin user and team in Mattermost.

    Returns the Mattermost id of the human account, which is also its
    ``external_user_id`` on the bridge — what linking it to a Switch user is
    keyed by. None when the account could not be created or read.
    """
    client = httpx.Client(base_url=MATTERMOST_URL, timeout=10)

    # Create admin user (first user becomes system admin)
    resp = client.post(
        "/api/v4/users",
        json={
            "username": MATTERMOST_ADMIN_USER,
            "password": MATTERMOST_ADMIN_PASSWORD,
            "email": MATTERMOST_ADMIN_EMAIL,
        },
    )
    if resp.status_code == 201:
        print(f"Created Mattermost admin user: {MATTERMOST_ADMIN_USER}")
    elif resp.status_code in (400, 409):
        print(f"Mattermost admin user already exists: {MATTERMOST_ADMIN_USER}")
    else:
        print(f"Unexpected response creating admin: {resp.status_code} {resp.text}")
        resp.raise_for_status()

    # Login to get token
    resp = client.post(
        "/api/v4/users/login",
        json={
            "login_id": MATTERMOST_ADMIN_USER,
            "password": MATTERMOST_ADMIN_PASSWORD,
        },
    )
    if not resp.is_success:
        print(
            f"ERROR: Could not login to Mattermost as {MATTERMOST_ADMIN_USER}: "
            f"{resp.status_code}. If the password changed, run: just down && just up"
        )
        sys.exit(1)
    token = resp.headers["token"]
    client.headers["Authorization"] = f"Bearer {token}"

    # Create team
    try:
        resp = client.post(
            "/api/v4/teams",
            json={
                "name": MATTERMOST_TEAM_NAME,
                "display_name": MATTERMOST_TEAM_NAME.capitalize(),
                "type": "O",
                "allow_open_invite": True,
            },
        )
        if resp.status_code == 201:
            print(f"Created Mattermost team: {MATTERMOST_TEAM_NAME}")
        elif resp.status_code == 400 and "already exists" in resp.text.lower():
            print(f"Mattermost team already exists: {MATTERMOST_TEAM_NAME}")
        else:
            resp.raise_for_status()
    except httpx.HTTPStatusError as e:
        print(f"Warning: Could not create team: {e}")

    # Get team ID and ensure open invite is enabled
    resp = client.get(f"/api/v4/teams/name/{MATTERMOST_TEAM_NAME}")
    resp.raise_for_status()
    team_id = resp.json()["id"]
    client.put(
        f"/api/v4/teams/{team_id}/patch",
        json={"allow_open_invite": True},
    )

    # Add admin to team
    admin_resp = client.get("/api/v4/users/me")
    admin_id = admin_resp.json()["id"]
    client.post(
        f"/api/v4/teams/{team_id}/members",
        json={"team_id": team_id, "user_id": admin_id},
    )

    # Create regular user
    try:
        resp = client.post(
            "/api/v4/users",
            json={
                "username": MATTERMOST_USER,
                "password": MATTERMOST_USER_PASSWORD,
                "email": MATTERMOST_USER_EMAIL,
            },
        )
        if resp.status_code == 201:
            user_id = resp.json()["id"]
            print(f"Created Mattermost user: {MATTERMOST_USER}")
        elif resp.status_code == 400 and "already exists" in resp.text.lower():
            print(f"Mattermost user already exists: {MATTERMOST_USER}")
            resp = client.get(f"/api/v4/users/username/{MATTERMOST_USER}")
            user_id = resp.json()["id"]
        else:
            resp.raise_for_status()
            user_id = resp.json()["id"]
    except httpx.HTTPStatusError as e:
        print(f"Warning: Could not create user: {e}")
        user_id = None

    # Add user to team
    if user_id:
        client.post(
            f"/api/v4/teams/{team_id}/members",
            json={"team_id": team_id, "user_id": user_id},
        )
        print(f"Added {MATTERMOST_USER} to team {MATTERMOST_TEAM_NAME}")

    client.close()
    return user_id


def gateway_login() -> httpx.Client:
    """A gateway client authenticated as the seeded admin.

    Bridge administration is admin-gated, so we log in as the seeded gateway
    admin (cookie-based JWT) and drive the same authorized endpoints the
    dashboard uses — there is no unauthenticated bridge-admin surface.

    The session cookie is then carried by hand rather than left to the cookie
    jar. A deployment served over HTTPS mints it with the Secure flag, and this
    job reaches switch-core over plain HTTP on its in-cluster address, so a
    conforming client accepts the cookie at login and declines to send it back:
    the login succeeds and every call after it is anonymous. Replaying the value
    as a header discloses nothing the login did not — the admin password crossed
    the same hop a moment earlier — and leaves the Secure flag doing its real
    job for browsers.
    """
    client = httpx.Client(base_url=SWITCH_URL, timeout=10)
    resp = client.post(
        "/gateway/auth/login",
        json={"email": GATEWAY_ADMIN_EMAIL, "password": GATEWAY_ADMIN_PASSWORD},
    )
    if not resp.is_success:
        print(
            "ERROR: Could not log in to the Switch gateway as "
            f"{GATEWAY_ADMIN_EMAIL}: {resp.status_code} {resp.text}"
        )
        sys.exit(1)
    token = resp.cookies.get("switch_auth")
    if token is None:
        print(
            "ERROR: The Switch gateway accepted the login as "
            f"{GATEWAY_ADMIN_EMAIL} but issued no switch_auth cookie, so the "
            "setup calls that follow cannot be authenticated."
        )
        sys.exit(1)
    client.headers["Cookie"] = f"switch_auth={token}"
    return client


def register_bridge(client: httpx.Client) -> str:
    """Register Mattermost bridge with Switch via the authorized gateway API.

    Returns the bridge id — the one already registered, or the new one. Every
    call it makes raises on failure, the read included: without a bridge there
    is no deployment to speak of, so none of it is something to carry on past.
    """
    # Check if bridge already registered. A read that answered with an error
    # status is not an empty list: taken as one, a 401 or a 503 mid-rollout
    # sends us on to registering a second Mattermost bridge and making it the
    # default, taking that from whatever held it. Refuse instead — this job is
    # retried, and a duplicated bridge cannot be undone by retrying. (A
    # timeout already raised out of the request itself and never got here.)
    resp = client.get("/gateway/collaborations")
    if not resp.is_success:
        print(
            "ERROR: Could not read the registered collaboration bridges: "
            f"{resp.status_code} {resp.text}"
        )
        resp.raise_for_status()
    bridges = resp.json()
    for bridge in bridges:
        if bridge.get("bridge_type") == "mattermost":
            bridge_id = bridge["bridge_id"]
            print(f"Mattermost bridge already registered: {bridge_id}")
            # Adopt the default on an instance that predates it, so an
            # existing deployment gains the invariant on its next setup run
            # rather than only new ones.
            if not any(b.get("is_default") for b in bridges):
                client.post(
                    f"/gateway/collaborations/{bridge_id}/default"
                ).raise_for_status()
                print(f"Set Mattermost bridge as default: {bridge_id}")
            # And mark it as the deployment's own, for a bridge registered
            # before the flag existed. Telemetry leaves a preconfigured
            # connector out of onboarding: it came up because the deployment
            # booted, not because anybody connected anything. A server that
            # predates the flag does not list it, and is left alone rather
            # than sent a field it would ignore.
            if bridge.get("preconfigured") is False:
                client.patch(
                    f"/gateway/collaborations/{bridge_id}",
                    json={"preconfigured": True},
                ).raise_for_status()
                print(f"Marked Mattermost bridge as preconfigured: {bridge_id}")
            # Same reason: a bridge registered before callbacks existed
            # would otherwise keep drawing cards with no buttons on them,
            # and the only cure would be editing a connection field by
            # hand. Sent every run rather than only when it is missing,
            # because the config a bridge holds is not readable back — it
            # carries the admin password, so no endpoint returns it.
            if MATTERMOST_CALLBACK_BASE_URL:
                client.patch(
                    f"/gateway/collaborations/{bridge_id}",
                    json={
                        "connection_config": {
                            "callback_base_url": MATTERMOST_CALLBACK_BASE_URL
                        }
                    },
                ).raise_for_status()
                print(
                    f"Set Mattermost callback address: {MATTERMOST_CALLBACK_BASE_URL}"
                )
            return bridge_id

    # Register new bridge
    connection_config: dict[str, str] = {
        "url": MATTERMOST_URL_FOR_SWITCH,
        "admin_user": MATTERMOST_ADMIN_USER,
        "admin_password": MATTERMOST_ADMIN_PASSWORD,
        "team_name": MATTERMOST_TEAM_NAME,
        # The bundled deployment's single human. Added to every channel this
        # bridge creates so they can read rooms that agents created without
        # naming any users — including private ones, which they could not
        # otherwise join.
        "default_member": MATTERMOST_USER,
    }
    if MATTERMOST_PUBLIC_URL:
        connection_config["public_url"] = MATTERMOST_PUBLIC_URL
    if MATTERMOST_CALLBACK_BASE_URL:
        connection_config["callback_base_url"] = MATTERMOST_CALLBACK_BASE_URL
    resp = client.post(
        "/gateway/collaborations",
        json={
            "bridge_type": "mattermost",
            "display_name": "Mattermost",
            "connection_config": connection_config,
            # The bundled Mattermost is the deployment's own chat, so it is
            # what rooms should bridge to when the caller names nothing.
            "set_as_default": True,
            # Registered by this step, not by a person, so it is not counted
            # as anyone connecting a platform.
            "preconfigured": True,
        },
    )
    resp.raise_for_status()
    data = resp.json()
    print(f"Registered Mattermost bridge: {data['bridge_id']} (default)")
    return data["bridge_id"]


def await_directory_account(
    client: httpx.Client, bridge_id: str, external_user_id: str
) -> bool:
    """Wait until the bridge's own directory lists the seeded human account.

    Registering a bridge records it; it does not mean its adapter has finished
    starting, and a claim for an account Switch has never seen is refused until
    it has (409). This probes the directory the claim itself consults, so a
    success here means the next call has what it needs rather than merely that
    some other endpoint answered.
    """
    for attempt in range(1, LINK_MAX_RETRIES + 1):
        resp = client.get(
            f"/gateway/collaborations/{bridge_id}/directory",
            params={"query": MATTERMOST_USER},
        )
        if resp.is_success:
            found = resp.json().get("users", [])
            if any(u.get("external_user_id") == external_user_id for u in found):
                return True
            reason = f"{MATTERMOST_USER} not in the directory yet"
        else:
            reason = f"{resp.status_code} {resp.text}"
        print(
            f"Waiting for the Mattermost bridge to serve its directory "
            f"({attempt}/{LINK_MAX_RETRIES}): {reason}"
        )
        time.sleep(RETRY_DELAY)
    return False


def link_owner_identity(
    client: httpx.Client, bridge_id: str, external_user_id: str
) -> None:
    """Link the seeded Mattermost account to the seeded gateway admin.

    The deployment provisions both halves of one person — a Switch admin and
    the Mattermost account they will chat from — so leaving them unassociated
    means owner-only addressing (CHOO-2137) cannot recognise the owner in the
    deployment's own chat, and the Home page reports an account the user has to
    link by hand (CHOO-2172).

    A link only counts once the account confirms it (CHOO-3881). A person does
    that by posting a code, which needs a channel with an agent in it to hear
    it, and a fresh deployment has none; so setup confirms it with the
    account's own Mattermost session instead, which it can open because it
    created the account.

    Only ever claims when the admin holds no identity on this bridge, or holds
    the seeded one unconfirmed, so a re-run is a no-op once it is confirmed.
    Someone who deliberately unlinks themselves and runs setup again does get
    relinked; that is the cost of repairing every existing
    deployment on its next run, and the manual control to undo it is still
    there.
    """
    resp = client.get("/gateway/auth/me/identities")
    if resp.is_success:
        on_bridge = [i for i in resp.json() if i.get("bridge_id") == bridge_id]
        # A link from before links needed confirming reads as unverified. One
        # to the seeded account is confirmed below like a new link; one the
        # admin made to some other account is theirs, and left alone.
        unconfirmed_seeded = [
            i
            for i in on_bridge
            if i.get("external_user_id") == external_user_id
            and not i.get("verified", True)
        ]
        if on_bridge and not unconfirmed_seeded:
            print(f"Gateway admin already linked to a Mattermost account: {bridge_id}")
            return
    else:
        print(
            "WARNING: Could not read the gateway admin's linked accounts: "
            f"{resp.status_code} {resp.text}"
        )
        return

    if not await_directory_account(client, bridge_id, external_user_id):
        print(
            f"WARNING: The Mattermost bridge never listed {MATTERMOST_USER} in its "
            f"directory, so {GATEWAY_ADMIN_EMAIL} was NOT linked to it. Owner-only "
            "agents will not recognise you in Mattermost until you link the account "
            "yourself from the server's Messaging apps section."
        )
        return

    resp = client.post(
        f"/gateway/collaborations/{bridge_id}/identities",
        json={
            "external_user_id": external_user_id,
            "username": MATTERMOST_USER,
            "expects_confirmation": True,
        },
    )
    if resp.is_success:
        identity = resp.json()
        if identity.get("link_request") is None:
            print(
                f"Linked {GATEWAY_ADMIN_EMAIL} to Mattermost account {MATTERMOST_USER}"
            )
        else:
            confirm_owner_identity(client, bridge_id, identity["id"])
        return
    print(
        f"WARNING: Could not link {GATEWAY_ADMIN_EMAIL} to the Mattermost account "
        f"{MATTERMOST_USER}: {resp.status_code} {resp.text}. Owner-only agents will "
        "not recognise you in Mattermost until you link the account yourself from "
        "the server's Messaging apps section."
    )


def confirm_owner_identity(
    client: httpx.Client, bridge_id: str, identity_id: str
) -> None:
    """Confirm the admin's waiting link with the seeded account's own session.

    The session is opened for this and closed straight after, so setup leaves
    no login of the account behind.
    """
    mattermost = httpx.Client(base_url=MATTERMOST_URL, timeout=10)
    try:
        login = mattermost.post(
            "/api/v4/users/login",
            json={"login_id": MATTERMOST_USER, "password": MATTERMOST_USER_PASSWORD},
        )
        if not login.is_success:
            print(
                f"WARNING: Could not sign in to Mattermost as {MATTERMOST_USER} "
                f"({login.status_code} {login.text}), so the link to "
                f"{GATEWAY_ADMIN_EMAIL} is waiting to be confirmed. Confirm it "
                "from the server's Messaging apps section."
            )
            return
        token = login.headers["token"]
        try:
            resp = client.post(
                f"/gateway/collaborations/{bridge_id}/identities/{identity_id}"
                "/verify-session",
                json={"token": token},
            )
        finally:
            mattermost.post(
                "/api/v4/users/logout", headers={"Authorization": f"Bearer {token}"}
            )
    finally:
        mattermost.close()
    if resp.is_success:
        print(f"Linked {GATEWAY_ADMIN_EMAIL} to Mattermost account {MATTERMOST_USER}")
        return
    print(
        f"WARNING: Could not confirm the link from {GATEWAY_ADMIN_EMAIL} to the "
        f"Mattermost account {MATTERMOST_USER}: {resp.status_code} {resp.text}. "
        "Owner-only agents will not recognise you in Mattermost until you confirm "
        "it from the server's Messaging apps section."
    )


def main() -> None:
    print("Switch local setup starting...")

    wait_for_service(f"{MATTERMOST_URL}/api/v4/system/ping", "Mattermost")
    mattermost_user_id = setup_mattermost()

    wait_for_service(f"{SWITCH_URL}/health", "Switch")
    client = gateway_login()
    try:
        bridge_id = register_bridge(client)
        if mattermost_user_id is None:
            print(
                f"WARNING: No Mattermost account for {MATTERMOST_USER}, so "
                f"{GATEWAY_ADMIN_EMAIL} could not be linked to one"
            )
        else:
            link_owner_identity(client, bridge_id, mattermost_user_id)
    finally:
        client.close()

    print("Setup complete!")


if __name__ == "__main__":
    main()