#shell/remote_protocol

#Wire contract

• Client requests: ResolveDirectory, OpenDocument, WatchDocument, CloseDocument, Hover, Definition, References, and DocumentSymbols.
• Server packets: directory/document results, watched DocumentChanged pushes, pushed Diagnostics, semantic feature results, and RemoteError.
• Position requests carry a document revision and UTF-16 offset; whole-document feature requests carry a revision. Request IDs correlate replies. Diagnostics deliberately have no request ID; watch pushes reuse the watch request ID.
• Definition results carry an ordered locations array; an empty array means that no definition was found.
• Decoders return structured errors for invalid JSON, version, packet shape, URI, or provider failure. provider_code preserves the lower-level category.
• Reference results add line, column, and line-text preview fields. There is no semantic-token packet.

#Version negotiation

sequenceDiagram
  participant C as browser workbench
  participant S as host server
  C->>S: ClientPacket { version: protocol_version() }
  alt version matches
    S-->>C: ServerPacket { version, payload }
  else version differs
    S-->>C: RemoteError (negotiation failed)
  end

///|
test "only the exact protocol version negotiates" {
  debug_inspect(
    (
      @remote_protocol.protocol_version(),
      @remote_protocol.negotiate_protocol_version(
        @remote_protocol.protocol_version(),
      ),
      @remote_protocol.negotiate_protocol_version(
        @remote_protocol.protocol_version() - 1,
      ),
      @remote_protocol.negotiate_protocol_version(999),
    ),
    content=(
      #|(
      #|  6,
      #|  ProtocolAccepted(6),
      #|  ProtocolRejected(
      #|    {
      #|      code: ProtocolUnsupportedVersion,
      #|      message: "Unsupported remote protocol version 5",
      #|      request_id: "",
      #|      provider_code: "",
      #|    },
      #|  ),
      #|  ProtocolRejected(
      #|    {
      #|      code: ProtocolUnsupportedVersion,
      #|      message: "Unsupported remote protocol version 999",
      #|      request_id: "",
      #|      provider_code: "",
      #|    },
      #|  ),
      #|)
    ),
  )
}

#Decoding

///|
test "malformed input decodes to a structured error, never a raise" {
  debug_inspect(
    ["", "not json at all", "{}", "{\"version\":1,\"kind\":\"hover\"}"].map(raw => {
      match @remote_protocol.decode_client_packet(raw) {
        DecodedClientPacket(_) => "decoded"
        ClientPacketDecodeError(error) => "error:" + error.code.to_string()
      }
    }),
    content=(
      #|[
      #|  "error:InvalidJson",
      #|  "error:InvalidJson",
      #|  "error:UnsupportedVersion",
      #|  "error:UnsupportedVersion",
      #|]
    ),
  )
}

///|
test "error codes round-trip, and unknown input falls back" {
  let codes : Array[@remote_protocol.ProtocolErrorCode] = [
    ProtocolInvalidJson,
    ProtocolUnsupportedVersion,
    ProtocolUnknownPacket,
    ProtocolInvalidPacket,
    ProtocolInvalidUri,
    ProtocolProviderError,
  ]
  debug_inspect(
    (
      codes.map(code => {
        (
          code.to_string(),
          @remote_protocol.ProtocolErrorCode::from_string(code.to_string()) ==
          code,
        )
      }),
      @remote_protocol.ProtocolErrorCode::from_string("SomethingNewer"),
    ),
    content=(
      #|(
      #|  [
      #|    ("InvalidJson", true),
      #|    ("UnsupportedVersion", true),
      #|    ("UnknownPacket", true),
      #|    ("InvalidPacket", true),
      #|    ("InvalidUri", true),
      #|    ("ProviderError", true),
      #|  ],
      #|  ProtocolInvalidPacket,
      #|)
    ),
  )
}

#Boundary and validation