UIP-0125.md

uip	0125
title	%eyre/%iris: Support Websocket
description	Support Websocket connections on Eyre/Iris
author	~fidwed-sipwyn
status	Stagnant
type	Standards Track
category	Kernel
created	2024-04-27

Abstract

This proposal adds Websocket functionality that works in a similar manner to the currently %eyre/%iris HTTP interface. Users who wish to receive Websocket connections will use the existing %eyre's %connect $task to bind a URL path where the websocket handshakes will arrive (since they are technically also HTTP requests, this should be intuitive). To initiate a connection, users should pass a %websocket-connect $task to %iris. Once the connection is established, the client/server vanes interaction with the apps occurs through %gall pokes, facts and subscriptions.

Motivation

Websocket support will allow Urbit to interact with a wider variety of systems/protocols.

Specification

• %eyre will have a new $gift and a new $task:

    ::  $gift
    ::
    ::  websocket-reponse: event to earth
    ::
    [%websocket-response event=websocket-event]
    ::  $task
    ::
    ::  receives websocket event from earth
    ::
    [%websocket-event event=websocket-event]

• And the following new types:

  ::  +websocket-connection: connection to be store in eyre state 
  ::
  +$  websocket-connection
    $:  app=term
        =inbound-request
    ==
  ::  +websocket-message:  websocket message content
  ::
  +$  websocket-message
    $:  opcode=@ud
        message=(unit data=octs)
    ==
  ::  +websocket-event:  inbound/outbound websocket event
  ::
  +$  websocket-event
    $%  [%accept ~]
        [%reject ~]
        [%disconnect ~]
        [%message message=websocket-message]
    ==
  ::

• %iris will have two new $gifts and two new $tasks:

  ::  $gift
  ::
  ::  %websocket-handshake: outbound websocket-handshake to earth
  ::
  [%websocket-handshake id=@ud url=@t]
  ::  %websocket-response: event to earth
  ::
  [%websocket-response id=@ud websocket-event:eyre]
  ::  $task
  ::
  ::  request to open websocket connection
  :: 
  [%websocket-connect app=term url=@t]
  ::  receives websocket event from earth
  ::
  [%websocket-event id=@ud event=websocket-event:eyre]

• And a new type:

  ::  +websocket-connection: websocket connection stored in iris state
  ::
  +$  websocket-connection
    $:  app=term
        =duct
        id=@ud
        url=@t
        status=?(%pending %accepted)
    ==

• %eyre will share the $websocket-message and $websocket-event types with %iris.
• The only new $task that the app devs will utilize is the %websocket-connect from iris.
• The existing %cancel-request $task from iris will be modified to also cancel websocket requests.
• Server user flow:
  • The user exposes their app with the %eyre's %connect $task.
  • When a handshake comes from earth, %eyre subscribes to the app's /websocket-server/[eyre-id] path and sends a %websocket-handshake poke with [eyre-id inbound-request]. The eyre-id will be used to represent that particular connection.
  • In response to %websocket-handshake, the user gives a fact with the %accept or %reject mark on /websocket-server/[eyre-id].
  • After %accepted the app can give %messages facts on /websocket-server/[eyre-id] and receives messages that comes as %websocket-server-messages pokes, containing [eyre-id websocket-message].
  • If the subscription is kicked, then the connection is closed, or the user can give a fact with the %disconnect mark to close it.
• Client user flow:
  • The user sends a request to initiate the connection by passing the %websocket-connect $task to %iris with [app=term url=@t].
  • The user can cancel the request by using the %cancel-request $task.
  • If the connection succeeds %iris will subscribe to /websocket-client/id, with id representing that particular connection.
  • The app can give facts with the %message mark on /websocket-client/id and receives messages that comes as %websocket-client-messages pokes, containing [id websocket-message].
  • If the subscription is kicked, then the connection is closed, or the user can give a fact with the %disconnect mark to close it.

Rationale

The approach followed here is a way to add the intended feature while reutilizing some of the existing logic and without adding a new vane.

Backwards Compatibility

Backwards compatibility is only affected if there are developers currently handling Websocket handshakes in the %handle-http-request poke.

Reference Implementation

Incoming

Security Considerations

Similar considerations as the currently HTTP implementation.

Copyright

Copyright and related rights waived via CC0.