episodes.list

{
  "type": "object",
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty"
}

{
  "type": "object",
  "properties": {
    "open": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many are open — held by a connection that is still there."
    },
    "detached": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many are detached, waiting for a client to come back inside the grace. Not a\nfault count: this is where a crashed client's work waits to be resumed."
    },
    "episodes": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ConnectionEpisode"
      },
      "description": "Every episode, open and detached, in external-identity order."
    },
    "mine": {
      "anyOf": [
        {
          "$ref": "#/$defs/ConnectionEpisode"
        },
        {
          "type": "null"
        }
      ],
      "description": "The episode the calling connection holds, when it holds one."
    }
  },
  "required": [
    "open",
    "detached",
    "episodes"
  ],
  "description": "The answer of `episodes.list`: every episode this server holds, counted by state, and the\none the caller holds. In memory only — it is the association between live connections and\nthe repository's records, which stops being true when the process stops.\n\nThe two counts partition the list, and `mine` is left out of the JSON rather than written\nas `null` when the caller holds nothing, which is always so over plain HTTP:\n\n```\nuse majordomus_cli::capability::builtin::episodes::EpisodeList;\nlet none = EpisodeList { open: 0, detached: 0, episodes: vec![], mine: None };\nlet json = serde_json::to_value(&none).unwrap();\nassert_eq!(json, serde_json::json!({\"open\": 0, \"detached\": 0, \"episodes\": []}));\nlet back: EpisodeList = serde_json::from_value(json).unwrap();\nassert_eq!(back.open + back.detached, back.episodes.len());\n```",
  "title": "EpisodeList",
  "$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```"
    }
  }
}