🥮 mooncakes.io
    Sign in

    tun-poc-proto

    Download zip
    Version
    0.3.3
    License
    Apache-2.0
    Repository
    Last updated
    2 months ago
    Downloads
    200

    #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
      RenderFrameState
      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_state

    source
    fn CapabilitySet::supports_render_frame_state(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
    }

    Cursor

    source
    pub(all) struct Cursor {
      x : Int
      y : Int
      shape : CursorShape
      blink : Bool
      color : String?
    } derive(Eq, 
    Debug    )

    The visible cursor. Coordinates are zero-based viewport cells; a cursor on a wide glyph's trailing cell is already snapped to the glyph head. color is set only when the child application overrides the cursor color, so the client theme keeps the default. The glyph under a block cursor, its cell span, and its inverted color are not on the wire: the client derives them from the run grid it already holds.
    impl ToJson for Cursor
    impl FromJson for Cursor

    CursorShape

    source
    pub(all) enum CursorShape {
      Block
      Bar
      Underline
    } derive(Eq, 
    Debug    )

    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

    Frame

    source
    pub(all) struct Frame {
      full : Bool
      styles : Array[RunStyle]
      lines : Array[Line]
      cursor : Cursor?
    } derive(Eq, 
    Debug    )

    Structured render payload for render_frame_state clients. The server diffs terminal state against what each client already holds, so lines carries only the rows to repaint unless full is set. Runs keep explicit col and width so the client can map text back to grid cells for selection without replaying a terminal emulator.

    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

    Line

    source
    pub(all) struct Line {
      y : Int
      runs : Array[Run]
    } derive(Eq, 
    Debug    )

    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

    Run

    source
    pub(all) struct Run {
      col : Int
      width : Int
      text : String
      style : Int?
    } derive(Eq, 
    Debug    )

    One styled run of cells. An ASCII run holds one cell per character, so width equals the character count. A non-ASCII glyph always forms its own run whose width (1 or 2) is its grid-cell span; the client renders it as a fixed-width centered span so glyph advances cannot push later columns off the grid.
    impl ToJson for Run
    impl FromJson for Run

    RunStyle

    source
    pub(all) struct RunStyle {
      fg : String?
      bg : String?
      underline_color : String?
      flags : Int
    } derive(Eq, 
    Debug    )

    Colors are #rrggbb; None means the client's default foreground or background. The server resolves palette indices (including bold promotion) but never substitutes its own default colors, so client themes keep owning the defaults — including under inverse, which the client applies by swapping resolved colors with its theme defaults.
    impl ToJson for RunStyle
    fn RunStyle::blink(self : RunStyle) -> Bool

    RunStyle::bold

    source
    fn RunStyle::bold(self : RunStyle) -> Bool

    RunStyle::conceal

    source
    fn RunStyle::conceal(self : RunStyle) -> Bool

    RunStyle::faint

    source
    fn RunStyle::faint(self : RunStyle) -> Bool

    RunStyle::inverse

    source
    fn RunStyle::inverse(self : RunStyle) -> Bool

    RunStyle::is_default

    source
    fn RunStyle::is_default(self : RunStyle) -> Bool

    Whether this is the default style a Run encodes as style : None.

    RunStyle::italic

    source
    fn RunStyle::italic(self : RunStyle) -> Bool

    RunStyle::new

    source
    fn RunStyle::new(fg? : String, bg? : String, underline_color? : String, bold? : Bool, faint? : Bool, italic? : Bool, strikethrough? : Bool, overline? : Bool, blink? : Bool, inverse? : Bool, conceal? : Bool, underline? : Underline) -> RunStyle

    RunStyle::overline

    source
    fn RunStyle::overline(self : RunStyle) -> Bool

    RunStyle::strikethrough

    source
    fn RunStyle::strikethrough(self : RunStyle) -> Bool

    RunStyle::underline

    source
    fn RunStyle::underline(self : RunStyle) -> Underline

    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)
      Title(title~ : String?)
      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
      title : 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?, mouse~ : Bool?, data~ : String)
      RenderState(client_id~ : String, seq~ : Int64, cols~ : Int, rows~ : Int, scroll_offset~ : Int64, scrollback_rows~ : Int64, title~ : String?, mouse~ : Bool?, frame~ : Frame)
      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)
      Theme(client_id~ : String, background~ : String, foreground~ : 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
    }

    Underline

    source
    pub(all) enum Underline {
      None
      Single
      Double
      Curly
      Dotted
      Dashed
    } derive(Eq, 
    Debug    )

    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