episodes.detach

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "external_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The episode to close. Omitted, it is whichever one this connection holds, which is\nwhat a client ending its own sitting means."
    }
  },
  "description": "The input of `episodes.detach`: the episode to close.\n\nEmpty is a valid input, meaning the episode the calling connection holds; over an\ninterface with no connection that input is refused, since there is nothing to take\n\"this one's episode\" from.\n\n```\nuse majordomus_cli::capability::builtin::episodes::DetachInput;\nlet mine: DetachInput = serde_json::from_str(\"{}\").unwrap();\nassert!(mine.external_id.is_none());\nlet named: DetachInput = serde_json::from_str(r#\"{\"external_id\":\"conv-42\"}\"#).unwrap();\nassert_eq!(named.external_id.as_deref(), Some(\"conv-42\"));\nassert_eq!(serde_json::to_string(&mine).unwrap(), \"{}\", \"an omitted id is not written as null\");\n```",
  "title": "DetachInput"
}

{
  "type": "object",
  "properties": {
    "episode": {
      "$ref": "#/$defs/ConnectionEpisode",
      "description": "The episode as it was closed, its `repository` field carrying what the repository's\nown end event reported."
    }
  },
  "required": [
    "episode"
  ],
  "description": "The answer of `episodes.detach`: the episode as it was closed, no longer held by any\nconnection, with what the repository's end event reported.\n\n```\nuse majordomus_cli::capability::builtin::episodes::Detached;\nlet schema = serde_json::to_value(schemars::schema_for!(Detached)).unwrap();\nassert_eq!(schema[\"required\"], serde_json::json!([\"episode\"]));\n```",
  "title": "Detached",
  "$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```"
    }
  }
}