fix(transport)!: added docs moved connection to connectionId (openwal…

…let-foundation#1222)

Signed-off-by: blu3beri <blu3beri@proton.me>

packages/core/src/agent/MessageReceiver.ts

@@ -147,7 +147,7 @@ export class MessageReceiver {
       // We allow unready connections to be attached to the session as we want to be able to
       // use return routing to make connections. This is especially useful for creating connections
       // with mediators when you don't have a public endpoint yet.
-      session.connection = connection ?? undefined
+      session.connectionId = connection?.id
       messageContext.sessionId = session.id
       this.transportService.saveSession(session)
     } else if (session) {

packages/core/src/agent/TransportService.ts

@@ -1,6 +1,5 @@
 import type { AgentMessage } from './AgentMessage'
 import type { EnvelopeKeys } from './EnvelopeService'
-import type { ConnectionRecord } from '../modules/connections/repository'
 import type { DidDocument } from '../modules/dids'
 import type { EncryptedMessage } from '../types'
 
@@ -16,7 +15,7 @@ export class TransportService {
   }
 
   public findSessionByConnectionId(connectionId: string) {
-    return Object.values(this.transportSessionTable).find((session) => session?.connection?.id === connectionId)
+    return Object.values(this.transportSessionTable).find((session) => session?.connectionId === connectionId)
   }
 
   public hasInboundEndpoint(didDocument: DidDocument): boolean {
@@ -36,12 +35,34 @@ interface TransportSessionTable {
   [sessionId: string]: TransportSession | undefined
 }
 
+// In the framework Transport sessions are used for communication. A session is
+// associated with a connection and it can be reused when we want to respond to
+// a message. If the message, for example, does not contain any way to reply to
+// this message, the session should be closed. When a new sequence of messages
+// starts it can be used again. A session will be deleted when a WebSocket
+// closes, for the WsTransportSession that is.
 export interface TransportSession {
+  // unique identifier for a transport session. This can a uuid, or anything else, as long
+  // as it uniquely identifies a transport.
   id: string
+
+  // The type is something that explicitly defines the transport type. For WebSocket it would
+  // be "WebSocket" and for HTTP it would be "HTTP".
   type: string
+
+  // The enveloping keys that can be used during the transport. This is used so the framework
+  // does not have to look up the associated keys for sending a message.
   keys?: EnvelopeKeys
+
+  // A received message that will be used to check whether it has any return routing.
   inboundMessage?: AgentMessage
-  connection?: ConnectionRecord
+
+  // A stored connection id used to find this session via the `TransportService` for a specific connection
+  connectionId?: string
+
+  // Send an encrypted message
   send(encryptedMessage: EncryptedMessage): Promise<void>
+
+  // Close the session to prevent dangling sessions.
   close(): Promise<void>
 }

packages/core/src/agent/__tests__/TransportService.test.ts

@@ -15,7 +15,7 @@ describe('TransportService', () => {
     test(`remove session saved for a given connection`, () => {
       const connection = getMockConnection({ id: 'test-123', role: DidExchangeRole.Responder })
       const session = new DummyTransportSession('dummy-session-123')
-      session.connection = connection
+      session.connectionId = connection.id
 
       transportService.saveSession(session)
       expect(transportService.findSessionByConnectionId(connection.id)).toEqual(session)

packages/core/src/agent/__tests__/stubs.ts

@@ -1,4 +1,3 @@
-import type { ConnectionRecord } from '../../modules/connections'
 import type { AgentMessage } from '../AgentMessage'
 import type { EnvelopeKeys } from '../EnvelopeService'
 import type { TransportSession } from '../TransportService'
@@ -8,7 +7,7 @@ export class DummyTransportSession implements TransportSession {
   public readonly type = 'http'
   public keys?: EnvelopeKeys
   public inboundMessage?: AgentMessage
-  public connection?: ConnectionRecord
+  public connectionId?: string
 
   public constructor(id: string) {
     this.id = id