Manage Connections

Manage peer connections that the agent has established

Connections are the gateway to DIDComm interactions with peers, whether that be receiving a credential, sending a credential proof, or more. After a connection has been established with a peer, the established connection will appear under the agent's ConnectionsModule where they are ready to be used and managed.

The functionality of the ConnectionsModule is accessed via the agent's fields: agent.connections. The functionality provided is described below.

Get a Connection by ID

Established connections are represented by Connection objects. To retrieve the current state of a specific Connection in the agent's wallet, the getById API can be used. If a connection cannot be found by the given identifier, then null is returned:

Swift

let id: String // ID of the connection to get ([Connection.connectionId])

do {
    let connection = try await agent.connections.getById(connectionId: id)
} catch {
    // handle error
}

Kotlin

val id: String // ID of the connection to get ([Connection.connectionId])

launch {
    try {
        val connection = agent.connections.getById(id)
    } catch (e: ConnectionsModule.GetException) {
        // Handle exception
    }
}

Delete a Connection by ID

Similarly, a Connection in the wallet can be easily deleted via the deleteById API:

Swift

let id: String // ID of the connection to delete ([Connection.connectionId])

do {
    try await agent.connections.deleteById(connectionId: id)
} catch {
    // handle error
}

Kotlin

val id: String // ID of the connection to delete ([Connection.connectionId])

launch {
    try {
        agent.connections.deleteById(id)
    } catch (e: ConnectionsModule.DeleteException) {
        // Handle exception
    }
}

Updating the Metadata of a Connection

Connection objects contain metadata that can be controlled by SDK consumers, allowing custom information to be attached to each Connection . It also allows custom listing functionality to be leveraged.

Each Connection contains a list of RecordTag (Connection.tags) attached to it, where a RecordTag is simply a name-value pair stored with the record. By default, some tags are attached to a new Connection. These include:

• tag-name: ~created_timestamp tag-value: The UNIX epoch seconds which this connection was established

The tags on a Connection can be replaced or updated by using the updateConnection API, and providing a new set to update. This will replace the current set of tags. An example follows:

Swift

let id: String // ID of the connection to update

// add a 'category' of 'work' to this connection, and a 'priority' of '1'
let update = ConnectionUpdate(tags: [
    RecordTag(name: "category", value: "work"),
    RecordTag(name: "~priority", value: "1")
])

do {
    try await agent.connections.updateConnection(connectionId: id, connectionUpdate: update)
} catch {
    // handle error
}

Kotlin

val id: String // ID of the connection to update ([Connection.connectionId])

// add a 'category' of 'work' to this connection, and a 'priority' of '1'
val update = ConnectionUpdate(
    tags = listOf(
         RecordTag("category", "work"),
         RecordTag("~priority", "1")   
    )
)

launch {
    try {
        agent.connections.updateConnection(id, update)
    } catch (e: ConnectionsModule.UpdateException) {
        // Handle exception
    }
}

Like most data in the wallet, RecordTag will be stored encrypted. Unless, the tag name is prefixed with ~, then the tag value will be stored unencrypted. Storing a tag value as unencrypted will allow some additional listing queries to be performed (see below).

Listing Connections

To list all connections in the agent's wallet, the listAll API can be used:

Swift

do {
    let conns = try await agent.connections.listAll(options: nil)
} catch {
    // handle error
}

Kotlin

launch {
    try {
        val conns: List<Connection> = agent.connections.listAll(null)
    } catch (e: ConnectionsModule.ListException) {
        // Handle exception
    }
}

Filtered Listing

More complicated Connection list queries can also be achieved by utilizing the ListConnectionsFilters.

To filter by tags applied to the Connection (i.e. applied via the update API), the tagFilter field of ListConnectionsFilters should be used. This field takes a String in compliance with a Wallet Query Langauge (WQL) Query.

Continuing from the example in the Update section:

Swift

// WQL Query, filter for 'category' == 'work'
let wqlQuery = "{ \"category\": \"work\" }"
let filters = ListConnectionsFilters(tagFilter: wqlQuery)
let options = ListConnectionsOptions(filters: filters)
do {
    let workConnections = try await agent.connections.listAll(options: options)
} catch {
    // handle error
}

// WQL Query, filter for priority < 2 (e.g. 'high' priority items)
let wqlQuery = "{ \"~priority\": { \"$lt\": \"2\" } }"
let filters = ListConnectionsFilters(tagFilter: wqlQuery)
let options = ListConnectionsOptions(filters: filters)

do {
    let highPriorityConnections = try await agent.connections.listAll(options: options)
} catch {
    // Handle error
}

Kotlin

// WQL Query, filter for 'category' == 'work'
val wqlQuery = """{ "category": "work" }"""
val filters = ListConnectionsFilters(tagFilter = wqlQuery)
val options = ListConnectionsOptions(filters)

launch {
    try {
        val workConnections = agent.connections.listAll(options)
    } catch (e: ConnectionsModule.ListException) {
        // Handle exception
    }
}

// WQL Query, filter for priority < 2 (e.g. 'high' priority items)
val wqlQuery = """{ "~priority": { "${"$"}lt": "2" } }"""
val filters = ListConnectionsFilters(tagFilter = wqlQuery)
val options = ListConnectionsOptions(filters)

launch {
    try {
        val highPriorityConnections = agent.connections.listAll(options)
    } catch (e: ConnectionsModule.ListException) {
        // Handle exception
    }
}