🥮 mooncakes.io
    Sign in

    tun-poc-proto

    Download zip
    Version
    0.1.3
    License
    Apache-2.0
    Repository
    Last updated
    5 months ago
    Downloads
    194

    #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 (session lifecycle, terminal I/O, resize, reconnection).
    • REST API payloads (auth, user status, server list).
    • Codex JSON-RPC envelopes and filesystem event types.
    • Newtype IDs (ServerId, UserId, GroupId) and typed serde for each message variant.

    See docs/protocol.md for the message flow.

    AddMemberRequest

    source
    pub(all) struct AddMemberRequest {
      login : 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(String)
      FileChange(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(CodexThreadResult)
      ThreadListResult(Array[CodexThreadResult])
      ThreadReadResult(CodexThreadResult, Array[CodexReadTurn])
      OtherResponse(Json)
      TurnStarted(CodexTurnId)
      TurnCompleted(CodexTurnId, CodexStatus)
      ItemStarted(CodexTurnId, CodexItemId, CodexItemKind, String, String)
      ItemCompleted(CodexTurnId, CodexItemId, CodexStatus)
      Delta(CodexTurnId, CodexItemId, String, CodexItemKind)
      ThreadStatusChanged(CodexThreadId, CodexActivityStatus)
      Approval(CodexRequestId, CodexThreadId, CodexTurnId, CodexItemId, 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(Int, CodexClientInfo)
      ThreadStart(Int, String)
      ThreadList(Int, String)
      ThreadRead(Int, CodexThreadId, Bool)
      ThreadResume(Int, CodexThreadId)
      TurnStart(Int, CodexThreadId, String)
      TurnInterrupt(Int, CodexThreadId, CodexTurnId)
      Initialized
      Approval(CodexRequestId, 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(String, String)
      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(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 {
      Stat(String, String, String)
      StatResult(String, String, FileStat)
      Readdir(String, String, String)
      ReaddirResult(String, String, Array[(String, Int)])
      ReadFile(String, String, String)
      ReadFileResult(String, String, String)
      WriteFile(String, String, String, String, Bool, Bool)
      Mkdir(String, String, String)
      FsDelete(String, String, String, Bool)
      FsRename(String, String, String, String, Bool)
      FsOk(String, String)
      FsError(String, String, String, 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
    }

    MachineAccessGroup

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

    Message

    source
    pub(all) enum Message {
      Sys(SysMessage)
      Fs(FsMessage)
      Term(TermMessage)
      Codex(String, 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(Int)
    } derive(Eq, 
    Debug    )

    RegisterRejectReason::to_wire

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

    SysMessage

    source
    pub(all) enum SysMessage {
      Register(
    UUID    , String, String, Int)
      Registered(
    UUID    )
      RegisterRejected(RegisterRejectReason)
      TaskExited(Int)
      Connect(
    UUID    , Int64?, Int)
      Connected
      TaskOnline
      NewClient(String, Int64?)
      ClientDisconnected(String)
      Error(ErrorCode)
      AuthError(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
    }

    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 {
      Data(String, Int64, Int64?, Bool?, String)
      Exited(String, 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
    }

    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 on every breaking change to Register/Connect or the sys-channel handshake. Both 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