legacyconnection

Documentation

Overview

Package legacyconnection enables relationship between two agents via Connection RFC-0160 Protocol. The connection request message is used to communicate the DID document of the invitee to the inviter using the provisional service information present in the invitation message. The connection response message is used to complete the connection and communicate the DID document of the inviter to the invitee. After inviter receives the connection response, the establishment of connection is technically complete however it is still unconfirmed to the inviter. The invitee sends ACK message to inviter to confirm the connection.

Basic Flow:
1) Prepare client context
2) Create client
3) Register for action events (enables auto execution)
4) Create Invitation
5) Handle invitation
6) Use connection

Example

bob, err := New(mockContext())
if err != nil {
	fmt.Println("failed to create client for Bob")
}

bobActions := make(chan service.DIDCommAction, 1)

err = bob.RegisterActionEvent(bobActions)
if err != nil {
	fmt.Println("failed to create Bob's action channel")
}

go func() {
	service.AutoExecuteActionEvent(bobActions)
}()

alice, err := New(mockContext())
if err != nil {
	fmt.Println("failed to create client for Alice")
}

aliceActions := make(chan service.DIDCommAction, 1)

err = alice.RegisterActionEvent(aliceActions)
if err != nil {
	fmt.Println("failed to create Alice's action channel")
}

go func() {
	service.AutoExecuteActionEvent(aliceActions)
}()

invitation, err := bob.CreateInvitation("bob invites alice")
if err != nil {
	fmt.Printf("failed to create invitation: %s\n", err)
}

connectionID, err := alice.HandleInvitation(invitation)
if err != nil {
	fmt.Printf("failed to handle invitation: %s\n", err)
}

connection, err := alice.GetConnection(connectionID)
if err != nil {
	fmt.Printf("failed to get connection: %s\n", err)
}

fmt.Println(connection.TheirLabel)

Output:

bob invites alice

Index

• Constants
• Variables
• type Client
  • func New(ctx provider) (*Client, error)
  • func (c *Client) AcceptConnectionRequest(connectionID, publicDID, label string, args ...Opt) error
  • func (c *Client) AcceptInvitation(connectionID, publicDID, label string, args ...Opt) error
  • func (c *Client) CreateConnection(myDID string, theirDID *did.Doc, options ...ConnectionOption) (string, error)
  • func (c *Client) CreateImplicitInvitation(inviterLabel, inviterDID string, args ...Opt) (string, error)
  • func (c *Client) CreateImplicitInvitationWithDID(inviter, invitee *DIDInfo) (string, error)
  • func (c *Client) CreateInvitation(label string, args ...InvOpt) (*Invitation, error)
  • func (c *Client) CreateInvitationWithDID(label, publicDID string) (*Invitation, error)
  • func (c *Client) GetConnection(connectionID string) (*Connection, error)
  • func (c *Client) GetConnectionAtState(connectionID, stateID string) (*Connection, error)
  • func (c *Client) HandleInvitation(invitation *Invitation) (string, error)
  • func (c *Client) QueryConnections(request *QueryConnectionsParams) ([]*Connection, error)
  • func (c *Client) RemoveConnection(connectionID string) error
• type Connection
• type ConnectionOption
  • func WithImplicit(i bool) ConnectionOption
  • func WithInvitationDID(didID string) ConnectionOption
  • func WithInvitationID(id string) ConnectionOption
  • func WithParentThreadID(pthid string) ConnectionOption
  • func WithTheirLabel(l string) ConnectionOption
  • func WithThreadID(thid string) ConnectionOption
• type DIDInfo
• type Event
• type InvOpt
  • func WithRouterConnectionID(conn string) InvOpt
• type Invitation
• type Opt
  • func WithRouterConnections(conns ...string) Opt
• type QueryConnectionsParams

Examples

• Package
• Client.CreateInvitation
• Client.CreateInvitationWithDID
• New

Constants

const InvitationMsgType = legacyconnection.InvitationMsgType

InvitationMsgType defines the connection invite message type.

Variables

var ErrConnectionNotFound = errors.New("connection not found")

ErrConnectionNotFound is returned when connection not found.

Types

type Client

type Client struct {
	service.Event
	// contains filtered or unexported fields
}

Client enable access to legacyconnection api.

func New

func New(ctx provider) (*Client, error)

New return new instance of legacyconnection client.

Example

ctx := mockContext()

c, err := New(ctx)
if err != nil {
	fmt.Println(err)
}

if c != nil {
	fmt.Println("client created")
} else {
	fmt.Println("client is nil")
}

Output:

client created

func (*Client) AcceptConnectionRequest

func (c *Client) AcceptConnectionRequest(connectionID, publicDID, label string, args ...Opt) error

AcceptConnectionRequest accepts/approves connection request. This call is not used if auto execute is setup for this client (see package example for more details about how to setup auto execute).

func (*Client) AcceptInvitation

func (c *Client) AcceptInvitation(connectionID, publicDID, label string, args ...Opt) error

AcceptInvitation accepts/approves connection invitation. This call is not used if auto execute is setup for this client (see package example for more details about how to setup auto execute).

func (*Client) CreateConnection

func (c *Client) CreateConnection(myDID string, theirDID *did.Doc, options ...ConnectionOption) (string, error)

CreateConnection creates a new connection between myDID and theirDID and returns the connectionID.

func (*Client) CreateImplicitInvitation

func (c *Client) CreateImplicitInvitation(inviterLabel, inviterDID string, args ...Opt) (string, error)

CreateImplicitInvitation enables invitee to create and send connection request using inviter public DID.

func (*Client) CreateImplicitInvitationWithDID

func (c *Client) CreateImplicitInvitationWithDID(inviter, invitee *DIDInfo) (string, error)

CreateImplicitInvitationWithDID enables invitee to create implicit invitation using inviter and invitee public DID.

func (*Client) CreateInvitation

func (c *Client) CreateInvitation(label string, args ...InvOpt) (*Invitation, error)

CreateInvitation creates an invitation. New key pair will be generated and did:key encoded public key will be used as basis for invitation. This invitation will be stored so client can cross-reference this invitation during connection protocol.

Example

bob, err := New(mockContext())
if err != nil {
	fmt.Println("failed to create client for Bob")
}

invitation, err := bob.CreateInvitation("bob invites julia")
if err != nil {
	fmt.Printf("failed to create invitation: %s\n", err)
}

fmt.Println(invitation.Label)

Output:

bob invites julia

func (*Client) CreateInvitationWithDID

func (c *Client) CreateInvitationWithDID(label, publicDID string) (*Invitation, error)

CreateInvitationWithDID creates an invitation with specified public DID. This invitation will be stored so client can cross reference this invitation during connection protocol.

Example

bob, err := New(mockContext())
if err != nil {
	fmt.Println("failed to create client for Bob")
}

invitation, err := bob.CreateInvitationWithDID("bob invites maria", "did:example:abc-123")
if err != nil {
	fmt.Printf("failed to create invitation with DID: %s\n", err)
}

fmt.Println(invitation.DID)

Output:

did:example:abc-123

func (*Client) GetConnection

func (c *Client) GetConnection(connectionID string) (*Connection, error)

GetConnection fetches single connection record for given id.

func (*Client) GetConnectionAtState

func (c *Client) GetConnectionAtState(connectionID, stateID string) (*Connection, error)

GetConnectionAtState fetches connection record for connection id at particular state.

func (*Client) HandleInvitation

func (c *Client) HandleInvitation(invitation *Invitation) (string, error)

HandleInvitation handle incoming invitation and returns the connectionID that can be used to query the state of legacy connection protocol. Upon successful completion of protocol, connection details will be used for securing communication between agents.

func (*Client) QueryConnections

func (c *Client) QueryConnections(request *QueryConnectionsParams) ([]*Connection, error)

QueryConnections queries connections matching given criteria(parameters).

func (*Client) RemoveConnection

func (c *Client) RemoveConnection(connectionID string) error

RemoveConnection removes connection record for given id.

type Connection

type Connection struct {
	*connection.Record
}

Connection model

This is used to represent query connection result.

type ConnectionOption

type ConnectionOption func(*Connection)

ConnectionOption allows you to customize details of the connection record.

func WithImplicit

func WithImplicit(i bool) ConnectionOption

WithImplicit sets Implicit on the connection record.

func WithInvitationDID

func WithInvitationDID(didID string) ConnectionOption

WithInvitationDID sets InvitationDID on the connection record.

func WithInvitationID

func WithInvitationID(id string) ConnectionOption

WithInvitationID sets InvitationID on the connection record.

func WithParentThreadID

func WithParentThreadID(pthid string) ConnectionOption

WithParentThreadID sets ParentThreadID on the connection record.

func WithTheirLabel

func WithTheirLabel(l string) ConnectionOption

WithTheirLabel sets TheirLabel on the connection record.

func WithThreadID

func WithThreadID(thid string) ConnectionOption

WithThreadID sets ThreadID on the connection record.

type DIDInfo

type DIDInfo struct {

	// the DID
	DID string

	// the label associated with DID
	Label string
}

DIDInfo model for specifying public DID and associated label.

type Event

type Event model.Event

Event properties related api. This can be used to cast Generic event properties to connection specific props.

type InvOpt

type InvOpt Opt

InvOpt represents option for the CreateInvitation function.

func WithRouterConnectionID

func WithRouterConnectionID(conn string) InvOpt

WithRouterConnectionID allows you to specify the router connection ID.

type Invitation

type Invitation struct {
	*legacyconnection.Invitation
}

Invitation model for connection invitation.

type Opt

type Opt func(*options)

Opt represents option function.

func WithRouterConnections

func WithRouterConnections(conns ...string) Opt

WithRouterConnections allows you to specify the router connections.

type QueryConnectionsParams

type QueryConnectionsParams struct {

	// Alias of connection invitation
	Alias string `json:"alias,omitempty"`

	// Initiator is Connection invitation initiator
	Initiator string `json:"initiator,omitempty"`

	// Invitation key
	InvitationKey string `json:"invitation_key,omitempty"`

	// Invitation ID
	InvitationID string `json:"invitation_id,omitempty"`

	// Parent threadID
	ParentThreadID string `json:"parent_thread_id,omitempty"`

	// MyDID is DID of the agent
	MyDID string `json:"my_did,omitempty"`

	// State of the connection invitation
	State string `json:"state"`

	// TheirDID is other party's DID
	TheirDID string `json:"their_did,omitempty"`

	// TheirRole is other party's role
	TheirRole string `json:"their_role,omitempty"`
}

QueryConnectionsParams model

Parameters for querying connections.