proto

package
Version: v0.0.0-...-b5d8682 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 1, 2019 License: BSD-3-Clause Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source
const PoRecvTimeout = 10 * time.Second

todo make this a configurable option

Variables

This section is empty.

Functions

func PrepareHosting

func PrepareHosting(ctx HoContext)

Properly export contextual artifacts (fields, methods, types, etc.) for hosting.

Types

type CoPoTask

type CoPoTask struct {
	// contains filtered or unexported fields
}

type Conver

type Conver interface {
	// be a cancellable context
	CancellableContext

	// conversation id
	Id() string

	// must NOT be nil
	Po() Posting
	// can be nil if in a send-only posting context
	Ho() Hosting

	// obtain remote execution result, in round trip (rpc) style, where `hint` can be:
	//   *) nil
	//     for simple value with no serialization, i.e.
	//     remote execution result object is formatted to a string by `%#v`;
	//     this string is sent back to local hosting context for evaluation;
	//     the evaluated value object is returned as `result`.
	//   *) a string
	//     for structured value to be serialized with BSON, i.e.
	//     remote execution result object is serialized to a `[]byte` buffer by `bson.Marshal()`;
	//     this buffer is sent back to local hosting context to be deserialized with `RecvBSON()`;
	//     where the `hint` string value will be passed as its `booter` argument, literally;
	//     the `out` value will be returned as `result`.
	//   *) <other fancy serializing schemas>
	//     <not implemented yet>
	Get(code string, hint interface{}) (result interface{}, err error)

	// send a piece of outbound script to run and yield its return value to conversation
	SendCode(code string) (err error)

	// send a bson object, which may be a map or a struct value, to remote conversation.
	// the `hint` string can be empty for remote to receive a `bson.M`,
	// or it must be a valid Go expression evaluates to a map, or a pointer to a struct,
	// whose type is either unnamed, or must be available within remote hosting context.
	SendBSON(o interface{}, hint string) error

	// send a binary data stream, the peer must understand the size and layout of this stream,
	// from previous posted scripts, actually it's expected previous scripts do trigger peer side
	// funcs to call `ho.CoRecvData()` with a chan of []byte buffers properly sized and laid out,
	// matching []bytes series posted here.
	SendData(data <-chan []byte) (err error)

	// receive an inbound data object created by landing scripts sent by peer
	// the scripts is expected to be sent from peer by `ho.CoSendCode()`
	RecvObj() (result interface{}, err error)

	// receive a bson object. if `booter` is nil, `out` will be a `bson.M`, else
	// out will be `booter` value as passed in.
	// the object is expected to be sent from peer by `co.SendBSON()` or `po.CoSendBSON()`.
	RecvBSON(nBytes int, booter interface{}) (out interface{}, err error)

	// receive an inbound binary data stream sent by peer
	// actually it's expected to be sent from peer by `po.CoSendData()`, the size and layout
	// should have been deducted from previous received data objects
	RecvData(data <-chan []byte) (err error)

	// finish this conversation to release the wire for other traffic
	Close()

	RecvTimeout() time.Duration
	SetRecvTimeout(time.Duration)
}

A conversation established upon a posting wire.

type HoContext

type HoContext interface {
	// be a cancellable context
	CancellableContext

	// return a slice of values, normally typed nil pointers or zero values,
	// whose value types are to be exposed to the hosting environment.
	TypesToExpose() []interface{}

	// execute code sent by peer and return last value as result
	Exec(code string) (result interface{}, ok bool, err error)

	// allow manipulation of contextual state objects
	Put(key string, value interface{})
	Get(key string) interface{}

	// the hosting endpoint embedding this HoContext
	Ho() Hosting
	SetHo(ho Hosting)

	// the posting endpoint bound to this context
	// can be nil for a receive only setup
	PoToPeer() Posting
	SetPoToPeer(po Posting)
	// panic instead of returning nil if no posting endpoint available
	MustPoToPeer() Posting

	Close()
}

The context for a service hosting endpoint.

An HBI gate struct will at least embed an interface of this type constructed by hbi.NewHoContext(), with service methods (and optionally some fields for service gate contextual states) defined to the struct in addition.

These methods (and setter/getter of fields) will be available (i.e. exposed) to HBI connection peers for scripted conversations & notifications.

Methods (include getters/setters) of this interface can be intercepted (overridden in Go's ways) by the HBI gate struct purposefully.

func NewHoContext

func NewHoContext() HoContext

type Hosting

type Hosting interface {
	HoContext
	HoCtx() HoContext

	// send code to the remote conversation.
	// must be in a passive local conversation responding to the remote conversation.
	CoSendCode(code string)

	// send a bson object, which may be a map or a struct value, to remote conversation.
	// must be in a passive local conversation responding to the remote conversation.
	// the `hint` string can be empty for remote to receive a `bson.M`,
	// or it must be a valid Go expression evaluates to a map, or a pointer to a struct,
	// whose type is either unnamed, or must be available within remote hosting context.
	CoSendBSON(o interface{}, hint string)

	// send a binary data stream to remote conversation.
	// must be in a passive local conversation responding to the remote conversation.
	CoSendData(<-chan []byte)

	// identity from the network's view
	NetIdent() string
	LocalAddr() net.Addr
	RemoteAddr() net.Addr

	// receive an inbound data object created by landing scripts sent by peer
	// the scripts is expected to be sent from peer by `co.SendCode()`
	CoRecvObj() (result interface{}, err error)

	// receive an inbound binary data stream sent by peer
	// the data stream is expected to be sent from peer by `co.SendData()`, the size and layout
	// should have been deducted from previous scripting landing or received data objects
	CoRecvData(data <-chan []byte) (err error)
}

type HostingEndpoint

type HostingEndpoint struct {
	HoContext
	// contains filtered or unexported fields
}

func NewHostingEndpoint

func NewHostingEndpoint(ctx HoContext) *HostingEndpoint

func (*HostingEndpoint) Cancel

func (ho *HostingEndpoint) Cancel(err error)

func (*HostingEndpoint) Close

func (ho *HostingEndpoint) Close()

func (*HostingEndpoint) CoRecvData

func (ho *HostingEndpoint) CoRecvData(data <-chan []byte) (err error)

func (*HostingEndpoint) CoRecvObj

func (ho *HostingEndpoint) CoRecvObj() (interface{}, error)

func (*HostingEndpoint) CoSendBSON

func (ho *HostingEndpoint) CoSendBSON(o interface{}, hint string)

func (*HostingEndpoint) CoSendCode

func (ho *HostingEndpoint) CoSendCode(code string)

func (*HostingEndpoint) CoSendData

func (ho *HostingEndpoint) CoSendData(data <-chan []byte)

func (*HostingEndpoint) HoCtx

func (ho *HostingEndpoint) HoCtx() HoContext

func (*HostingEndpoint) LocalAddr

func (ho *HostingEndpoint) LocalAddr() net.Addr

func (*HostingEndpoint) NetIdent

func (ho *HostingEndpoint) NetIdent() string

func (*HostingEndpoint) PlugWire

func (ho *HostingEndpoint) PlugWire(
	netIdent string, localAddr, remoteAddr net.Addr,
	recvPacket func() (*Packet, error),
	recvData func(data <-chan []byte) (n int64, err error),
	closer func() error,
)

func (*HostingEndpoint) RemoteAddr

func (ho *HostingEndpoint) RemoteAddr() net.Addr

func (*HostingEndpoint) StartLandingLoops

func (ho *HostingEndpoint) StartLandingLoops()

type Packet

type Packet struct {
	WireDir string
	Payload string
}

func (Packet) Format

func (pkt Packet) Format(s fmt.State, verb rune)

func (Packet) String

func (pkt Packet) String() string

type Posting

type Posting interface {
	// be a cancellable context
	CancellableContext

	// identity from the network's view
	NetIdent() string
	LocalAddr() net.Addr
	RemoteAddr() net.Addr

	// post a notification to the peer
	Notif(code string) (err error)

	// post a notification with a bson object to the peer
	NotifBSON(code string, o interface{}, hint string) error

	// post a notification with a binary data stream to the peer
	NotifData(code string, data <-chan []byte) (err error)

	// the hosting endpoint
	Ho() Hosting

	// initiate a local conversation
	// a conversation will hog the underlying posting wire until closed,
	// during which course other traffics, including notifications and other conversations will queue up.
	// so the shorter conversations be, the higher overall system throughput will gain.
	Co() (co Conver, err error)

	Close()
}

The context for a service posting endpoint.

type PostingEndpoint

type PostingEndpoint struct {
	// embed a cancellable context
	CancellableContext
	// contains filtered or unexported fields
}

func NewPostingEndpoint

func NewPostingEndpoint() *PostingEndpoint

func (*PostingEndpoint) Cancel

func (po *PostingEndpoint) Cancel(err error)

func (*PostingEndpoint) Close

func (po *PostingEndpoint) Close()

func (*PostingEndpoint) Co

func (po *PostingEndpoint) Co() (co Conver, err error)

func (*PostingEndpoint) Ho

func (po *PostingEndpoint) Ho() Hosting

func (*PostingEndpoint) LocalAddr

func (po *PostingEndpoint) LocalAddr() net.Addr

func (*PostingEndpoint) NetIdent

func (po *PostingEndpoint) NetIdent() string

func (*PostingEndpoint) Notif

func (po *PostingEndpoint) Notif(code string) (err error)

func (*PostingEndpoint) NotifBSON

func (po *PostingEndpoint) NotifBSON(code string, o interface{}, hint string) (err error)

func (*PostingEndpoint) NotifData

func (po *PostingEndpoint) NotifData(code string, data <-chan []byte) (err error)

func (*PostingEndpoint) PlugWire

func (po *PostingEndpoint) PlugWire(
	netIdent string, localAddr, remoteAddr net.Addr,
	sendPacket func(payload, wireDir string) (n int64, err error),
	sendData func(data <-chan []byte) (n int64, err error),
	closer func() error,
	ho *HostingEndpoint,
)

func (*PostingEndpoint) RemoteAddr

func (po *PostingEndpoint) RemoteAddr() net.Addr

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL