# SSB Rooms — Specification

Rooms is a subprotocol of [SSB Tunnels](https://github.com/ssbc/ssb-tunnel), which in turn is a subprotocol of [secret-stack](https://github.com/ssbc/secret-stack). Below are different use cases of rooms and their respective UML sequence diagram.

## Setting up a Room in DigitalOcean

(OPTIONAL)

**Assumptions:**

- Alice has read instructions about rooms
- Alice has set up an account in DigitalOcean
- Alice has a link to the DO Installer
- Alice will be the room's owner

sequenceDiagram
    participant A as Alice
    participant DOI as DO Installer
    participant R as New Room server
    
    A->>DOI: /GET HTML page
    Activate DOI
    Note over A,DOI: Complete steps on this page
    DOI->>R: Creates
    DOI-->>A: Page with link to URL of new room
    Deactivate DOI
    
    A->>R: /GET HTML page
    Activate R
    R-->>A: Page asking to configure room NAME and DESCRIPTION
    Deactivate R
    
    A->>R: /POST with NAME and DESCRIPTION
    Activate R
    R-->>A: Default page showing room's info and SSB invite
    Deactivate R

## Joining the Room by visiting its website

**Assumptions:**

- The room has been setup (see above) as public
- Alice in this case can be anyone

sequenceDiagram
    participant A as Alice
    participant R as Room
    
    A->>R: /GET HTML page
    Activate R
    R-->>A: Default page showing room's info and SSB invite
    Deactivate R
    
    A->>A: unwrap the invite as `msAddr`
    A->>R: this.conn.connect(msAddr)
    activate R
    R-->>A: done
    deactivate R
    
    A->>R: rpc.tunnel.isRoom
    activate R
    R-->>A: yes
    deactivate R
    
    A->>R: rpc.tunnel.announce(aliceId)
    activate R
    Note over A,R: Set up streams according to ssb-tunnel
    R-->>A: ok
    deactivate R
    
    A->>R: rpc.tunnel.endpoints()
    activate A
    activate R
    R-->>A: [aliceId, bobId]
    
    loop On announce()
        R-->>A: [aliceId, bobId, ..., NEWPEER]
    end
    deactivate R
    deactivate A

## Joining the Room using only its hostname

**Assumptions:**

- The room has been setup as public
- Specific to this example, `theroom.com` is the hostname of this Room
- Port 26819 is part of the protocol, not specific to this example
- Alice in this case can be anyone

sequenceDiagram
  participant A as Alice
  participant R as Room
  
  A->>R: GET theroom.com:26819/whois
  Activate R
  R-->>A: msAddr="net:theroom.com~shs:roomID"
  A->>R: this.conn.connect(msAddr)
  activate R
  R-->>A: done
  deactivate R
    
  A->>R: rpc.tunnel.isRoom
  activate R
  R-->>A: yes
  deactivate R
    
  A->>R: rpc.tunnel.announce(aliceId)
  activate R
  Note over A,R: Set up streams according to ssb-tunnel
  R-->>A: ok
  deactivate R
  
  A->>R: rpc.tunnel.endpoints()
  activate A
  activate R
  R-->>A: [aliceId]
  deactivate R
  deactivate A

## Connecting to a friend's Room alias

An alias is a username registered at a specific Room server, and an alias address is something like `@[e-mail]` or `@myusername:theroom.com` (format not decided yet). Any person who knows the Bob's alias address can connect to Bob if he is currently online in the Room.

**Assumptions:**

- The room has been setup as public
- Specific to this example, `theroom.com` is the hostname of this Room
- Port 26819 is part of the protocol, not specific to this example
- Bob is online in the Room
- Alice and Bob were not friends before

sequenceDiagram
  participant A as Alice
  participant R as Room
  participant B as Bob
  
  A->>A: unwrap alias address to get hostname
 
  A->>R: GET theroom.com:26819/whois
  Activate R
  R-->>A: msAddr="net:theroom.com~shs:roomID"
  A->>R: this.conn.connect(msAddr)
  activate R
  R-->>A: done
  deactivate R
  
  A->>R: rpc.tunnel.isRoom
  activate R
  R-->>A: yes
  deactivate R
    
  A->>R: rpc.tunnel.announce(aliceId)
  activate R
  Note over A,R: Set up streams according to ssb-tunnel
  R-->>A: ok
  deactivate R
  
  A->>R: rpc.tunnel.endpoints()
  activate A
  activate R
  R-->>A: [aliceId, bobId]
  deactivate R
  deactivate A
  
  A->>R: rpc.tunnel.whois('bob') 
  activate R
  R-->>A: @bobID
  deactivate R
  
  A->>A: follow @bobID
  
  A->>R: rpc.tunnel.connect(bobId)
  activate R
  R->>B: rpc.tunnel.connect(bobId)
  activate B
  B-->>R: set up duplex stream
  deactivate B
  R-->>A: set up duplex stream
  deactivate R

## Establishing new friendships through the Room

**Assumptions:**

- The room has been setup
- Alice has joined the Room (see above)
- Bob has also joined the Room (see above)
- Alice and Bob were not friends before

sequenceDiagram
    participant A as Alice
    participant R as Room
    participant B as Bob
    
    A->>R: rpc.tunnel.endpoints()
    activate R
    R-->>A: [aliceId, bobId]
    deactivate R
    
    B->>R: rpc.tunnel.endpoints()
    activate R
    R-->>B: [aliceId, bobId]
    deactivate R
    
    note over A: Conscious choice
    A->>A: follow Bob
    
    A->>R: rpc.tunnel.connect(bobId)
    activate R
    R->>B: rpc.tunnel.connect(bobId)
    activate B
    B-->>R: set up duplex stream
    deactivate B
    R-->>A: set up duplex stream
    deactivate R
    
    note over B: Conscious choice
    B->>B: follow Alice
    
    B->>R: rpc.tunnel.connect(aliceId)
    activate R
    R->>A: rpc.tunnel.connect(aliceId)
    activate A
    A-->>R: set up duplex stream
    deactivate A
    R-->>B: set up duplex stream
    deactivate R

## Connecting to existing friendships through the Room

**Assumptions:**

- The room has been setup
- Alice has joined the Room
- Bob has also joined the Room

sequenceDiagram
    participant A as Alice
    participant R as Room
    participant B as Bob
    
    A->>R: rpc.tunnel.endpoints()
    activate R
    R-->>A: [aliceId, bobId]
    deactivate R
    
    opt If Alice follows Bob
        A->>R: rpc.tunnel.connect(bobId)
        activate R
        R->>B: rpc.tunnel.connect(bobId)
        activate B
        B-->>R: set up duplex stream
        deactivate B
        R-->>A: set up duplex stream
        deactivate R
    end