episodes.attach

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "external_id": {
      "type": "string",
      "description": "The client's own durable name for this episode — its conversation id, thread id, or\nwhatever it calls the sitting it is in.\n\n**It must survive a reconnect**, because that is the whole of its job: a client that\ncomes back under the same identity is given its own episode again rather than a\nsecond one. Anything the client can reproduce will do; what will not do is this\nserver's peer id, which is handed out per connection and is a different string every\ntime the client reconnects."
    }
  },
  "required": [
    "external_id"
  ],
  "description": "The input of `episodes.attach`: which piece of work this connection is carrying.\n\nThe identity is the only field, and an unknown one is refused rather than ignored, so a\nclient that sends a peer id under another name learns it at once:\n\n```\nuse majordomus_cli::capability::builtin::episodes::AttachInput;\nlet input: AttachInput = serde_json::from_str(r#\"{\"external_id\":\"conv-42\"}\"#).unwrap();\nassert_eq!(input.external_id, \"conv-42\");\nassert!(serde_json::from_str::<AttachInput>(r#\"{\"external_id\":\"x\",\"peer\":\"p1\"}\"#).is_err());\nassert!(serde_json::from_str::<AttachInput>(\"{}\").is_err(), \"the identity is required\");\n```",
  "title": "AttachInput"
}

{
  "type": "object",
  "properties": {
    "episode": {
      "$ref": "#/$defs/ConnectionEpisode",
      "description": "The episode this connection now holds."
    },
    "resumed": {
      "type": "boolean",
      "description": "Whether an episode already under this identity was resumed rather than a new one\nopened. True after a reconnect, a client restart or a crash, and the field a caller\nchecks to know whether it is continuing something."
    },
    "reattach_grace_seconds": {
      "type": "integer",
      "format": "uint64",
      "minimum": 0,
      "description": "How long this episode survives its connection before the reaper closes it, in\nseconds. Stated rather than left to be discovered: a client that knows the grace can\ndecide whether reconnecting is worth it."
    }
  },
  "required": [
    "episode",
    "resumed",
    "reattach_grace_seconds"
  ],
  "description": "The answer of `episodes.attach`: the episode the connection now holds, whether it was\nresumed rather than opened, and how long it outlives a lost connection.\n\n```\nuse majordomus_cli::capability::builtin::episodes::Attached;\nlet schema = serde_json::to_value(schemars::schema_for!(Attached)).unwrap();\nfor field in [\"episode\", \"resumed\", \"reattach_grace_seconds\"] {\n    assert!(schema[\"required\"].as_array().unwrap().iter().any(|f| f == field), \"{field}\");\n}\n```",
  "title": "Attached",
  "$defs": {
    "ConnectionEpisode": {
      "type": "object",
      "properties": {
        "external_id": {
          "type": "string",
          "description": "The client's own durable name for this piece of work, and the key everything here is\naddressed by. Never a peer id: see the module documentation."
        },
        "provider": {
          "type": "string",
          "description": "The provider id this episode is recorded under, as `share/providers.yaml` names one."
        },
        "peer": {
          "anyOf": [
            {
              "$ref": "#/$defs/PeerId"
            },
            {
              "type": "null"
            }
          ],
          "description": "The connection holding it, when one does. `None` while detached — which is a state\nan episode is *supposed* to reach and come back from, not a fault."
        },
        "opened_at": {
          "type": "string",
          "description": "When it was first opened, RFC 3339, UTC. Unchanged by a re-attach: the episode is\nthe work, and the work did not restart because a socket did."
        },
        "last_activity_seconds_ago": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Seconds since the client last spoke on it, through any connection."
        },
        "attachments": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "How many times a connection has taken it over, the first attach included."
        },
        "state": {
          "$ref": "#/$defs/ConnectionEpisodeState",
          "description": "Open, or detached and waiting for its client."
        },
        "repository": {
          "type": "string",
          "description": "What the repository's own episode command reported, verbatim — the record it opened,\nor the reason it could not. Never interpreted here, and never empty: a subsystem\nthat silently does nothing is the failure mode this field exists to make visible."
        }
      },
      "required": [
        "external_id",
        "provider",
        "opened_at",
        "last_activity_seconds_ago",
        "attachments",
        "state",
        "repository"
      ],
      "description": "One episode: what the client calls itself, which connection holds it now, and what the\nrepository did about it.\n\n```\nuse majordomus_cli::episodes::{ConnectionEpisode, EpisodeBoard};\nuse majordomus_cli::peers::{PeerBoard, Transport};\nlet peer = PeerBoard::new().attach(Transport::Http);\nlet (episode, _) = EpisodeBoard::new().attach(&peer, \"conv-42\", \"generic\");\nlet episode: ConnectionEpisode = episode;\nassert_eq!((episode.external_id.as_str(), episode.provider.as_str()), (\"conv-42\", \"generic\"));\nassert_eq!(episode.peer.as_ref(), Some(&peer));\n// never empty: a board with no repository behind it says so\nassert!(episode.repository.contains(\"without a driver\"));\n```"
    },
    "PeerId": {
      "type": "string",
      "description": "A peer's identity for the life of the server: `p1`, `p2`, ... in attachment order.\n`p1` is the session that started the server."
    },
    "ConnectionEpisodeState": {
      "oneOf": [
        {
          "type": "string",
          "const": "open",
          "description": "A connection holds it and the client is speaking."
        },
        {
          "type": "string",
          "const": "detached",
          "description": "The connection has gone; the episode is kept for `REATTACH_GRACE` so the client\ncan come back to it. This is the state a crash lands in, and the one a reconnect\nrecovers from."
        }
      ],
      "description": "Where an episode stands: held by a live connection, or waiting for its client to come\nback. There is no closed state, because a closed episode leaves the board; what survives\nit is the repository's own record.\n\n```\nuse majordomus_cli::episodes::{ConnectionEpisodeState, EpisodeBoard};\nuse majordomus_cli::peers::{PeerBoard, Transport};\nlet peer = PeerBoard::new().attach(Transport::Stdio);\nlet board = EpisodeBoard::new();\nassert_eq!(board.attach(&peer, \"w\", \"generic\").0.state, ConnectionEpisodeState::Open);\nassert_eq!(board.detach(&peer)[0].state, ConnectionEpisodeState::Detached);\nassert_eq!(serde_json::to_string(&ConnectionEpisodeState::Detached).unwrap(), \"\\\"detached\\\"\");\n```"
    }
  }
}