🥮 mooncakes.io
    Sign in

    tun-poc-proto

    Download zip
    Version
    0.3.2
    License
    Apache-2.0
    Repository
    Last updated
    2 months ago
    Downloads
    202

    #tun-poc-proto

    Shared wire protocol types for tun-poc. Imported by the browser client, the relay, and the server agent so all three stay in sync.

    Covers:

    • Relay ↔ client and relay ↔ server messages (task lifecycle, terminal I/O, render viewports, replay, reconnection).
    • REST API payloads (auth, user status, task list, machines, groups, and administration).
    • Codex JSON-RPC envelopes and filesystem event types.
    • Task UUIDs, machine/group/user payloads, and typed JSON codecs for each message variant.

    See docs/protocol.md for the message flow.

    AddMemberRequest

    source
    pub(all) struct AddMemberRequest {
      login : String
    }

    Capability

    source
    pub(all) enum Capability {
      RenderFrameVt
      ViewportResize
      ServerScrollback
      ClientAttachAck
      MoonIdeHover
      FilesystemWatch
      Unknown(String)
    } derive(Eq, 
    Debug    )

    Capability::from_wire

    source
    fn Capability::from_wire(value : String) -> Capability

    Capability::to_wire

    source
    fn Capability::to_wire(self : Capability) -> String

    CapabilitySet

    source
    pub struct CapabilitySet(Array[Capability]) derive(Eq, 
    Debug    )

    CapabilitySet::empty

    source

    CapabilitySet::from_wire

    source
    fn CapabilitySet::from_wire(values : Array[String]) -> CapabilitySet

    CapabilitySet::length

    source
    fn CapabilitySet::length(self : CapabilitySet) -> Int

    CapabilitySet::new

    source

    CapabilitySet::supports

    source
    fn CapabilitySet::supports(self : CapabilitySet, capability : Capability) -> Bool

    CapabilitySet::supports_client_attach_ack

    source
    fn CapabilitySet::supports_client_attach_ack(self : CapabilitySet) -> Bool

    CapabilitySet::supports_filesystem_watch

    source
    fn CapabilitySet::supports_filesystem_watch(self : CapabilitySet) -> Bool

    CapabilitySet::supports_moon_ide_hover

    source
    fn CapabilitySet::supports_moon_ide_hover(self : CapabilitySet) -> Bool

    CapabilitySet::supports_render_frame_vt

    source
    fn CapabilitySet::supports_render_frame_vt(self : CapabilitySet) -> Bool

    CapabilitySet::supports_server_scrollback

    source
    fn CapabilitySet::supports_server_scrollback(self : CapabilitySet) -> Bool

    CapabilitySet::supports_viewport_resize

    source
    fn CapabilitySet::supports_viewport_resize(self : CapabilitySet) -> Bool

    CapabilitySet::to_log_string

    source
    fn CapabilitySet::to_log_string(self : CapabilitySet) -> String

    CapabilitySet::to_wire

    source
    fn CapabilitySet::to_wire(self : CapabilitySet) -> Array[String]

    CodexActiveFlag

    source
    pub(all) enum CodexActiveFlag {
      WaitingOnApproval
      WaitingOnUserInput
    } derive(Eq, 
    Debug    )

    CodexActivityStatus

    source
    pub(all) enum CodexActivityStatus {
      NotLoaded
      Idle
      Active(Array[CodexActiveFlag])
      SystemError
    } derive(Eq, 
    Debug    )

    CodexApproval

    source
    pub(all) enum CodexApproval {
      Command(command~ : String)
      FileChange(reason~ : String)
    }

    CodexApprovalDecision

    source
    pub(all) enum CodexApprovalDecision {
      Accept
      Decline
    }

    CodexClientInfo

    source
    pub(all) struct CodexClientInfo {
      name : String
      title : String
      version : String
    }

    CodexIncoming

    source
    pub(all) enum CodexIncoming {
      ThreadResult(thread~ : CodexThreadResult)
      ThreadListResult(threads~ : Array[CodexThreadResult])
      ThreadReadResult(thread~ : CodexThreadResult, turns~ : Array[CodexReadTurn])
      OtherResponse(id~ : Json)
      TurnStarted(turn_id~ : CodexTurnId)
      TurnCompleted(turn_id~ : CodexTurnId, status~ : CodexStatus)
      ItemStarted(turn_id~ : CodexTurnId, item_id~ : CodexItemId, kind~ : CodexItemKind, text~ : String, command~ : String)
      ItemCompleted(turn_id~ : CodexTurnId, item_id~ : CodexItemId, status~ : CodexStatus)
      Delta(turn_id~ : CodexTurnId, item_id~ : CodexItemId, delta~ : String, kind~ : CodexItemKind)
      ThreadStatusChanged(thread_id~ : CodexThreadId, activity~ : CodexActivityStatus)
      Approval(id~ : CodexRequestId, thread_id~ : CodexThreadId, turn_id~ : CodexTurnId, item_id~ : CodexItemId, approval~ : CodexApproval)
    }

    CodexItemId

    source
    pub(all) struct CodexItemId(String) derive(Eq, 
    Debug    )

    CodexItemKind

    source
    pub(all) enum CodexItemKind {
      AgentMessage
      UserMessage
      CommandExecution
      FileChange
      Reasoning
    } derive(Eq, 
    Debug    )

    CodexOutgoing

    source
    pub(all) enum CodexOutgoing {
      Initialize(id~ : Int, client_info~ : CodexClientInfo)
      ThreadStart(id~ : Int, cwd~ : String)
      ThreadList(id~ : Int, cwd~ : String)
      ThreadRead(id~ : Int, thread_id~ : CodexThreadId, include_turns~ : Bool)
      ThreadResume(id~ : Int, thread_id~ : CodexThreadId)
      TurnStart(id~ : Int, thread_id~ : CodexThreadId, input~ : String)
      TurnInterrupt(id~ : Int, thread_id~ : CodexThreadId, turn_id~ : CodexTurnId)
      Initialized
      Approval(id~ : CodexRequestId, decision~ : CodexApprovalDecision)
    }

    CodexReadItem

    source
    pub(all) struct CodexReadItem {
      id : CodexItemId
      kind : CodexItemKind
      text : String
      command : String
      output : String
    }

    CodexReadTurn

    source
    pub(all) struct CodexReadTurn {
      id : CodexTurnId
      items : Array[CodexReadItem]
      status : CodexStatus
    }

    CodexRequestId

    source
    pub(all) struct CodexRequestId(Json)

    CodexStatus

    source
    pub(all) enum CodexStatus {
      InProgress
      Completed
      Failed
    } derive(Eq, 
    Debug    )

    CodexThreadId

    source
    pub(all) struct CodexThreadId(String) derive(Eq, 
    Debug    )

    CodexThreadResult

    source
    pub(all) struct CodexThreadResult {
      id : CodexThreadId
      preview : String
      status : CodexThreadStatus
      activity : CodexActivityStatus
    } derive(Eq, 
    Debug    )

    CodexThreadStatus

    source
    pub(all) enum CodexThreadStatus {
      Open
      Archived
      Closed
    } derive(Eq, 
    Debug    )

    CodexTurnId

    source
    pub(all) struct CodexTurnId(String) derive(Eq, 
    Debug    )

    CreateGroupRequest

    source
    pub(all) struct CreateGroupRequest {
      name : String
    }

    CreateMachineRequest

    source
    pub(all) struct CreateMachineRequest {
      name : String
    }

    CreateMachineResponse

    source
    pub(all) struct CreateMachineResponse {
      token : String
      machine_id : Int
    }

    CreatedGroupResponse

    source
    pub(all) struct CreatedGroupResponse {
      id : Int
    }

    DeviceApproveRequest

    source
    pub(all) struct DeviceApproveRequest {
      code : String
    }

    Request body of POST /device/approve. Sent by the SPA when the user clicks Approve on the pairing page.

    DeviceAuthorizationRequest

    source
    pub(all) struct DeviceAuthorizationRequest {
      hostname : String
    }

    DeviceAuthorizationResponse

    source
    pub(all) struct DeviceAuthorizationResponse {
      device_code : String
      user_code : String
      verification_uri : String
      verification_uri_complete : String?
      expires_in : Int
      interval : Int
    }

    DeviceDenyRequest

    source
    pub(all) struct DeviceDenyRequest {
      code : String
    }

    Request body of POST /device/deny. Sent by the SPA when the user clicks Deny on the pairing page.

    DevicePendingResponse

    source
    pub(all) struct DevicePendingResponse {
      hostname : String
    }

    Response body of GET /device/pending?code=<user_code>. Returned to the SPA approval page so it can render the hostname the agent reported.

    DeviceTokenError

    source
    pub(all) enum DeviceTokenError {
      AuthorizationPending
      SlowDown
      ExpiredToken
      AccessDenied
      InvalidRequest
      UnsupportedGrantType
      Unknown(String)
    }

    RFC 8628 §3.5 token-endpoint error codes, plus Unknown(String) as a forward-compatibility hatch for codes added by a future relay against an older server. Wire format is a bare JSON string (see DeviceTokenResponse::Error).

    DeviceTokenRequest

    source
    pub(all) struct DeviceTokenRequest {
      grant_type : String
      device_code : String
    }

    DeviceTokenResponse

    source
    pub(all) enum DeviceTokenResponse {
      Success(access_token~ : String, token_type~ : String)
      Error(error~ : DeviceTokenError)
    }

    RFC 8628 §3.5 token-endpoint response. Discriminated on the wire by which field is present: access_token → Success, error → Error.

    ErrorCode

    source
    pub(all) enum ErrorCode {
      TaskNotFound
      TaskOffline
      InternalError
      ProtoVersionTooOld(min_version~ : Int)
    } derive(Eq, 
    Debug    )

    ErrorCode::to_wire

    source
    fn ErrorCode::to_wire(self : ErrorCode) -> String

    FileStat

    source
    pub(all) struct FileStat {
      file_type : Int
      size : Int64
      mtime : Int64
      ctime : Int64
    } derive(
    Debug    )

    impl ToJson for FileStat

    FileStat::to_log_string

    source
    fn FileStat::to_log_string(self : FileStat) -> String

    FsMessage

    source
    pub(all) enum FsMessage {
      WatchFile(req_id~ : String, client_id~ : String, path~ : String)
      UnwatchFile(req_id~ : String, client_id~ : String)
      WatchFileReady(req_id~ : String, client_id~ : String, path~ : String, resolved_path~ : String)
      FileChanged(req_id~ : String, client_id~ : String, path~ : String, resolved_path~ : String)
      Stat(req_id~ : String, client_id~ : String, path~ : String)
      StatResult(req_id~ : String, client_id~ : String, stat~ : FileStat)
      Readdir(req_id~ : String, client_id~ : String, path~ : String)
      ReaddirResult(req_id~ : String, client_id~ : String, entries~ : Array[(String, Int)])
      ReadFile(req_id~ : String, client_id~ : String, path~ : String)
      ReadFileResult(req_id~ : String, client_id~ : String, data~ : String)
      WriteFile(req_id~ : String, client_id~ : String, path~ : String, data~ : String, create~ : Bool, overwrite~ : Bool)
      Mkdir(req_id~ : String, client_id~ : String, path~ : String)
      FsDelete(req_id~ : String, client_id~ : String, path~ : String, recursive~ : Bool)
      FsRename(req_id~ : String, client_id~ : String, from~ : String, to~ : String, overwrite~ : Bool)
      FsOk(req_id~ : String, client_id~ : String)
      FsError(req_id~ : String, client_id~ : String, code~ : String, message~ : String)
    } derive(
    Debug    )

    impl ToJson for FsMessage

    FsMessage::client_id

    source
    fn FsMessage::client_id(self : FsMessage) -> String

    FsMessage::to_log_string

    source
    fn FsMessage::to_log_string(self : FsMessage) -> String

    GrantAccessRequest

    source
    pub(all) struct GrantAccessRequest {
      group_id : Int
    }

    GroupInfo

    source
    pub(all) struct GroupInfo {
      id : Int
      name : String
      owner_id : Int64
    }

    GroupMember

    source
    pub(all) struct GroupMember {
      github_id : Int64
      login : String
      avatar_url : String
    }

    IdeErrorCode

    source
    pub(all) enum IdeErrorCode {
      InvalidRequest
      MoonUnavailable
      MoonIdeFailed
      IdeTimeout
    } derive(Eq, 
    Debug    )

    Fixed error classifications for the Moon IDE hover channel.

    IdeErrorCode::from_wire

    source
    fn IdeErrorCode::from_wire(value : String) -> IdeErrorCode?

    IdeErrorCode::to_wire

    source
    fn IdeErrorCode::to_wire(self : IdeErrorCode) -> String

    IdeMessage

    source
    pub(all) enum IdeMessage {
      Hover(req_id~ : String, client_id~ : String, path~ : String, line~ : Int, column~ : Int)
      CancelHover(req_id~ : String, client_id~ : String)
      HoverResult(req_id~ : String, client_id~ : String, path~ : String, range~ : String?, contents~ : Array[String])
      IdeError(req_id~ : String, client_id~ : String, path~ : String, code~ : IdeErrorCode, message~ : String)
    } derive(
    Debug    )

    Moon IDE hover messages. Positions and compact ranges use one-based Unicode code-point coordinates, matching moon ide hover.

    IdeMessage::client_id

    source
    fn IdeMessage::client_id(self : IdeMessage) -> String

    IdeMessage::to_log_string

    source
    fn IdeMessage::to_log_string(self : IdeMessage) -> String

    MachineAccessGroup

    source
    pub(all) struct MachineAccessGroup {
      group_id : Int
      name : String
    }

    Message

    source
    pub(all) enum Message {
      Sys(SysMessage)
      Fs(FsMessage)
      Ide(IdeMessage)
      Term(TermMessage)
      Codex(client_id~ : String, data~ : String)
    } derive(
    Debug    )

    impl ToJson for Message
    impl FromJson for Message

    Message::client_id

    source
    fn Message::client_id(self : Message) -> String

    Message::to_log_string

    source
    fn Message::to_log_string(self : Message) -> String

    RegisterRejectReason

    source
    pub(all) enum RegisterRejectReason {
      UuidAlreadyClaimedThisSession
      InvalidUuid
      ProtoVersionTooOld(min_version~ : Int)
    } derive(Eq, 
    Debug    )

    RegisterRejectReason::to_wire

    source
    fn RegisterRejectReason::to_wire(self : RegisterRejectReason) -> String

    SysMessage

    source
    pub(all) enum SysMessage {
      Register(task_uuid~ : 
    UUID    , hostname~ : String, cwd~ : String, proto_version~ : Int, server_capabilities~ : CapabilitySet)
      Registered(task_uuid~ : 
    UUID    )
      RegisterRejected(reason~ : RegisterRejectReason)
      TaskExited(exit_code~ : Int)
      Connect(task_uuid~ : 
    UUID    , last_seen_id~ : Int64?, proto_version~ : Int, client_capabilities~ : CapabilitySet)
      Connected(server_proto_version~ : Int, server_capabilities~ : CapabilitySet)
      TaskOnline(server_proto_version~ : Int, server_capabilities~ : CapabilitySet)
      NewClient(client_id~ : String, last_seen_id~ : Int64?, client_proto_version~ : Int, client_capabilities~ : CapabilitySet)
      ClientDisconnected(client_id~ : String)
      Error(ErrorCode)
      AuthError(message~ : String)
    }

    impl Debug for SysMessage

    SysMessage::client_id

    source
    fn SysMessage::client_id(self : SysMessage) -> String

    SysMessage::to_log_string

    source
    fn SysMessage::to_log_string(self : SysMessage) -> String

    TaskEntry

    source
    pub(all) struct TaskEntry {
      task_uuid : 
    UUID
      machine_id : Int
      hostname : String
      cwd : String
      owner : String
      online : Bool
      last_seen_at : Int64
    } derive(Eq)

    Flat row for the GET /api/tasks listing. One row per running task instance (keyed by task_uuid), joined with its parent machine's display info. machine_id groups tasks that belong to the same long-lived machine; task_uuid is the identity used everywhere else on the wire.
    impl ToJson for TaskEntry

    TermMessage

    source
    pub(all) enum TermMessage {
      ClientReplayCursor(client_id~ : String, last_seen_id~ : Int64?)
      Viewport(client_id~ : String, cols~ : Int, rows~ : Int, active~ : Bool)
      RenderFrame(client_id~ : String, seq~ : Int64, cols~ : Int, rows~ : Int, scroll_offset~ : Int64, scrollback_rows~ : Int64, title~ : String?, data~ : String)
      InputText(client_id~ : String, text~ : String)
      InputKey(client_id~ : String, key~ : String, mods~ : Array[String], text~ : String?)
      InputPaste(client_id~ : String, text~ : String)
      InputMouse(client_id~ : String, x~ : Int, y~ : Int, button~ : String, action~ : String, mods~ : Array[String])
      InputScroll(client_id~ : String, x~ : Int, y~ : Int, delta_rows~ : Int, mods~ : Array[String])
      ScrollToLive(client_id~ : String)
      Data(client_id~ : String, id~ : Int64, created~ : Int64?, replay~ : Bool?, data~ : String)
      Exited(client_id~ : String, id~ : Int64)
    } derive(
    Debug    )

    TermMessage::client_id

    source
    fn TermMessage::client_id(self : TermMessage) -> String

    TermMessage::to_log_string

    source
    fn TermMessage::to_log_string(self : TermMessage) -> String

    TransferGroupRequest

    source
    pub(all) struct TransferGroupRequest {
      new_owner_id : Int64
    }

    UserInfo

    source
    pub(all) struct UserInfo {
      github_id : Int64
      login : String
      avatar_url : String
      status : UserStatus
      is_admin : Bool
    } derive(Eq)

    UserStatus

    source
    pub(all) enum UserStatus {
      Pending
      Approved
      Rejected
    } derive(Eq, 
    Debug    )

    UserStatus::from_string

    source
    fn UserStatus::from_string(s : String) -> UserStatus

    UserStatus::to_string

    source
    fn UserStatus::to_string(self : UserStatus) -> String

    ProtoMinVersion

    source
    let ProtoMinVersion : Int

    Lowest proto_version the relay accepts on Register/Connect. Bump to match ProtoVersion when dropping support for a prior version.

    ProtoVersion

    source
    let ProtoVersion : Int

    Wire protocol version this build speaks. Bumped when peers need to reason about a new protocol capability or when a breaking Register/Connect/sys-channel handshake change lands. Optional version fields default to 0 so peers built before versioning was introduced decode as version 0 — fully backwards compatible.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io