Initial Connection Figures

planning/ThingDescription/td-next-work-items/usability-and-design.md

@@ -72,32 +72,136 @@ Related Issues:
   - The initial connection must not be mandatory to establish upon TD consumption and should left to the implementation when to establish and close it.
 
 **Notes:**
+
 - When to close the connection needs to be discussed.
 - Complex security mechanisms exchange should be handled at the same time
 
-#### Examples of Message Flow
+#### Examples of Message Sequences
+
+##### Simple HTTP Connection
+
+###### Participating Entities
+
+![Participating Entities](./images/initial-connection-HTTP-entities.png)
+
+In this case, the Thing has enough resources and contains its own HTTP server.
+
+###### Lifecycle of a Connection
+
+![Lifecycle of a Connection](./images/initial-connection-HTTP-lifecycle.png)
+
+1. A request from the client opens the connection to the server.
+2. A response from the server back to the client closes the connection.
+3. If the server provides no response in a given time interval, a timeout occurs and the connection is closed.
+4. Alternatively, a request can be sent with Keep Alive parameters (timeout and max requests parameters).
+5. In this case, the responses back to the client will not close the connection.
+6. If a certain amount of requests have been sent, the connection will be closed.
+7. If a certain time is reached, the connection will be closed.
+
+###### Message Sequence
+
+![Message Sequence](./images/initial-connection-HTTP-sequence.png)
+
+We note that even with Keep Alive option set, the interaction pattern do not change in the application level.
+Thus, keep alive can be seen as an optimization and not a different way to interact.
+
+##### Broker Connections without Security
+
+###### Participating Entities
+
+![Participating Entities](./images/initial-connection-Broker-entities.png)
+
+Typically, the broker is a separate entity than the Thing.
+
+###### Lifecycle of a Connection
+
+![Lifecycle of a Connection](./images/initial-connection-Broker-lifecycle-connection.png)
+
+1. A client connects to the broker and opens a consistent connection.
+2. Client can subscribe or publish to topics as long as the connection is active.
+3. Client can disconnect from the broker and close the connection.
+4. If the device turns off or has an error, the connection can be closed.
+
+###### Lifecycle of a Subscription
+
+![Lifecycle of a Subscription](./images/initial-connection-Broker-lifecycle-subscription.png)
+
+1. A Client already connected to the broker (open connection), can subscribe to a topic where that subscription becomes active.
+2. Multiple messages can be received while the subscription is active.
+3. Once the client unsubscribes from the topic, the subscription becomes inactive.
+
+###### Message Sequence
+
+![Message Sequence](./images/initial-connection-Broker-sequence.png)
 
-- No security Broker Connections
+We note that, even after a time has passed, the connection stays open and the subscription stays active.
+The client id is used in a connection but is typically not exposed to the application layer.
 
-> Example message flow here
+##### Basic WebSocket Connections
 
-- WebSocket with Subprotocol Connection
+###### Participating Entities
 
-> Example message flow from WebThings here
+![Participating Entities](./images/initial-connection-WS-entities.png)
 
-> Example message flow from Socket.io here
+In this case, the Thing has enough resources and contains its own WebSocket server.
 
-> Example message flow from CoAP over WS here (see https://www.rfc-editor.org/rfc/rfc8323.html)
+###### Lifecycle of a Connection
 
-- Initial Token/Credential exchange
+![Lifecycle of a Websocket connection](./images/initial-connection-Websocket-lifecycle.png)
 
-> Example message flow here
+The lifecycle of a WebSocket connection in the Web of Things typically includes the following stages:
 
-- Proxy-based Communication
+1. **Connection Establishment**: The client initiates a handshake request to the server, which responds with a handshake response, establishing a persistent connection.
+2. **Data Transmission**: Once connected, the client and server can exchange data bi-directionally in real-time, with messages sent as frames. This may include ping/pong frames to keep understand connection "liveness" between the parties. 
+3. **Connection Closure**: Either party can initiate the closing handshake by sending a close frame, after which the connection is terminated, and resources are released.
 
-> Example message flow here
+
+###### Message Sequence
+
+![Message Sequence](./images/initial-connection-WS-sequence.png)
+
+##### OAuth2-based Interaction
+
+###### Participating Entities
+
+![Participating Entities](./images/initial-connection-Oauth2-entities.png)
+
+In this case, the Thing has enough resources and contains its own HTTP server.
+
+###### Lifecycle of a Session
+
+![Lifecycle of a Oauth Session](./images/initial-connection-OAuth2-lifecycle.png)
+
+The lifecycle of an OAuth token in a session involves the following stages:
+
+1. **Token Request and authorization**: The client requests an access token from the authorization server, typically after authenticating and obtaining user consent.
+2. **Token Use**: The client uses the access token to access protected resources on the resource server by including it in API requests.
+3. **Logout**: The client or authorization server can revoke tokens to terminate the session, preventing further access.
+4. **Token Expiry and Refresh**: Access tokens are time-limited. If a refresh token is available, the client can request a new access token without user reauthorization.
+
+
+###### Message Sequence
+
+![Message Sequence](./images/initial-connection-Oauth2-sequence.png)
+
+##### Proxy-based Communication
+
+###### Participating Entities
+
+![Participating Entities](./images/initial-connection-Proxy-entities.png)
+
+In this case, the Thing has enough resources and contains its own HTTP server.
+
+###### Lifecycle of a Connection
+
+TODO
+
+###### Message Sequence
+
+![Message Sequence](./images/initial-connection-Proxy-sequence.png)
 
 ### Data Schema Mapping
+
 ![GitHub labels](https://img.shields.io/github/labels/w3c/wot-thing-description/data%20mapping)
 
 Also known as: Mapping TD elements to messages