begin

Documentation

Overview

Package begin provides a chain element that can be put at the beginning of the chain, after Connection.Id has been set but before any chain elements that would mutate the Connection on the return path. the begin.New{Client,Server}() guarantee:

Scope

All Request() or Close() events are scoped to a particular Connection, uniquely identified by its Connection.Id

Exclusivity

Only one event is processed for a Connection.Id at a time

Order

Events for a given Connection.Id are processed in the order in which they are received

Close Correctness

When a Close(Connection) event is received, begin will replace the Connection provided with the last Connection successfully returned from the chain for Connection.Id

Midchain Originated Events

A midchain element may originate a Request() or Close() event to be processed from the beginning of the chain (Timeout, Refresh,Heal):

errCh := begin.FromContext(ctx).Request()
errCh := begin.FromContext(ctx).Close()

errCh will receive any error from the firing of the event, and will be closed after the event has fully processed.

Note: if a chain is a server chain continued by a client chain, the beginning of the chain is at the beginning of the server chain, even if there is a subsequent begin.NewClient() in the client chain.

Optionally you may use the CancelContext(context.Context) option:

begin.FromContext(ctx).Request(CancelContext(cancelContext))
begin.FromContext(ctx).Close(CancelContext(cancelContext))

If cancelContext is canceled prior to the processing of the event, the event processing will be skipped, and the errCh returned simply closed.

Midchain Originated Request Event

Example:

begin.FromContext(ctx).Request()

will use the networkservice.NetworkServiceRequest from the chain's last successfully completed Request() event with networkservice.NetworkServiceRequest.Connection replaced with the Connection returned by the chain's last successfully completed Request() event

Chain Placement

begin.New{Server/Client} should always proceed any chain element which: - Maintains state - Mutates the Connection object along the return path of processing a Request() event.

Reasoning

networkservice.NetworkService{Client,Server} processes two kinds of events:

• Request()
• Close()

Each Request() or Close() event is scoped to a networkservice.Connection, which can be uniquely identified by its Connection.Id

For a given Connection.Id, at most one event can be processed at a time (exclusivity). For a given Connection.Id, events must be processed in the order they were received (order). For Close(), the Connection passed to it must be identical to the last one returned by the chain to insure all state is correctly cleared (close correctness).

Typically, a chain element receives a Request() or Close() event from the element before it in the chain and sends a Request() or Close() and either terminates processing returning an error, or sends a Request() or Close() event to the next element in the chain.

There are some circumstances in which a Request() or Close() event needs to be originated by a chain element in the middle of the chain, but processed from the beginning of the chain. Examples include (but are not limited to):

• A server timing out an expired Connection
• A client refreshing a Connection so that it does not expire
• A client healing from a lost Connection

In all of these cases, the Request() or Close() event should be processed starting at the beginning of the chain, to ensure that all of the proper side effects occur within the chain.

Code generated by "-output ns_client_map.gen.go -type nsClientMap<string,*eventNSFactoryClient> -output ns_client_map.gen.go -type nsClientMap<string,*eventNSFactoryClient>"; DO NOT EDIT.

Code generated by "-output ns_server_map.gen.go -type nsServerMap<string,*eventNSFactoryServer> -output ns_server_map.gen.go -type nsServerMap<string,*eventNSFactoryServer>"; DO NOT EDIT.

Code generated by "-output nse_client_map.gen.go -type nseClientMap<string,*eventNSEFactoryClient> -output nse_client_map.gen.go -type nseClientMap<string,*eventNSEFactoryClient>"; DO NOT EDIT.

Code generated by "-output nse_server_map.gen.go -type nseServerMap<string,*eventNSEFactoryServer> -output nse_server_map.gen.go -type nseServerMap<string,*eventNSEFactoryServer>"; DO NOT EDIT.

Index

• func NewNetworkServiceEndpointRegistryClient() registry.NetworkServiceEndpointRegistryClient
• func NewNetworkServiceEndpointRegistryServer() registry.NetworkServiceEndpointRegistryServer
• func NewNetworkServiceRegistryClient() registry.NetworkServiceRegistryClient
• func NewNetworkServiceRegistryServer() registry.NetworkServiceRegistryServer
• type EventFactory
  • func FromContext(ctx context.Context) EventFactory
• type Option
  • func CancelContext(cancelCtx context.Context) Option

Functions

func NewNetworkServiceEndpointRegistryClient

func NewNetworkServiceEndpointRegistryClient() registry.NetworkServiceEndpointRegistryClient

NewNetworkServiceEndpointRegistryClient - returns a new null client that does nothing but call next.NetworkServiceEndpointRegistryClient(ctx).

func NewNetworkServiceEndpointRegistryServer

func NewNetworkServiceEndpointRegistryServer() registry.NetworkServiceEndpointRegistryServer

NewNetworkServiceEndpointRegistryServer - returns a new null server that does nothing but call next.NetworkServiceEndpointRegistryServer(ctx).

func NewNetworkServiceRegistryClient

func NewNetworkServiceRegistryClient() registry.NetworkServiceRegistryClient

NewNetworkServiceRegistryClient - returns a new null client that does nothing but call next.NetworkServiceRegistryClient(ctx).

func NewNetworkServiceRegistryServer

func NewNetworkServiceRegistryServer() registry.NetworkServiceRegistryServer

NewNetworkServiceRegistryServer - returns a new null server that does nothing but call next.NetworkServiceRegistryServer(ctx).

Types

type EventFactory

type EventFactory interface {
	Register(opts ...Option) <-chan error
	Unregister(opts ...Option) <-chan error
}

EventFactory - allows firing off a Request or Close event from midchain

func FromContext

func FromContext(ctx context.Context) EventFactory

FromContext - returns EventFactory from context

type Option

type Option func(*option)

Option - event option

func CancelContext

func CancelContext(cancelCtx context.Context) Option

CancelContext - optionally provide a context that, when canceled will preclude the event from running