qabalwrap

package module
v0.0.17 Latest Latest
Warning

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

 Go to latest Published: Mar 24, 2023 License: MIT Imports: 21 Imported by: 0

README

Restrictions

  • All custom defined identifier must alphabet-number only.
    • Automatically generated identifier will contain dashes.
  • Service Identify Numbers (ServiceIdent) must be positive 16-bits integers (int16).
    • Packaging into 2 bytes.

Design Notes

Services

  • Message Switch
    • Service Register
    • Certificate Manager
  • Access Gate
    • HTTP server
    • HTTP client
  • Content Edge
  • Content Fetcher
  • HTTP Server

Accesses from Message Switch to Services

HTTP Server
  • Start
  • Stop
  • Certificate change

Runtime Co-Routines

  • Service Routines: Activate and Deactivated by Message Switch via invoke Start() and Stop() methods of service.
  • Message Switch Management Routine: Management internal states such as status of access provider, modify service records. Operations in this routine should response as soon as possible.
  • Message Switch Maintenance (Fulfill) Routine: Invokes callbacks of services to notify response of request is ready. Operations in this routine may blocked for longer time.

Runtime Stages

  • Setup
  • Start
  • Run / Operation
  • Stop

Build Commands

Protocal Buffer Stub

protoc --proto_path=. --go_out=./gen/qbw1grpcgen --go_opt=paths=source_relative message-idl.proto

Diagnosis RPC Stub

protoc -I ./ ./diagnosis-idl.proto --go_out=./gen/qbw1diagrpcgen --go_opt=paths=source_relative --go-grpc_out=./gen/qbw1diagrpcgen --go-grpc_opt=paths=source_relative

Service Binary

go build github.com/qabalwrap/qabalwrap-1/cmd/qabalwrapd

Documentation

Index

Constants

View Source 
const (
	PrimaryMessageSwitchServiceIdent   int = 0
	AssignableServiceIdentMin              = 1
	AssignableServiceIdentMax              = (8192 - 1)
	AccessProviderPeerServiceIdent         = math.MaxInt16 - 2
	MessageSwitchBroadcastServiceIdent     = math.MaxInt16 - 1
	UnknownServiceIdent                    = -1
)
View Source 
const (
	ServiceTypeTextUnknown        = "unknown-service"
	ServiceTypeTextMessageSwitch  = "message-switch"
	ServiceTypeTextAccessProvider = "access-provider"
	ServiceTypeTextHTTPServer     = "http-server"
	ServiceTypeTextHTTPFetcher    = "http-fetcher"
	ServiceTypeTextHTTPEdge       = "http-edge"
)
View Source 
const (
	ContentIdentLocalServiceRef    = "local-service-ref"
	ContentIdentServiceRefs        = "service-refs"
	ContentIdentCertificateManager = "cert-manager"
)

Content identifiers for marshaling and unmarshaling.

View Source 
const DefaultTraceBufferSize = 16
View Source 
const MaxServiceIdentLength = 128

MaxServiceIdentLength define max length of service identifier.

Variables

View Source 
var DefaultMessageHops = [...]int{
	0,
	1,
	5,
	3,
	3,
	3,
	3,
	5,
	5,
	1,
	1,
	5,
}
View Source 
var ErrDeprecated = errors.New("deprecated")

ErrDeprecated indicate requested feature is deprecated and not implemented.

View Source 
var ErrEmptyIdentifier = errors.New("given service identifier is empty or contain none valid character")

ErrEmptyIdentifier indicate given identifier is empty or totally invalid.

View Source 
var ErrMessageContentTooSmall = errors.New("message content too small")

ErrMessageContentTooSmall indicate the message content is too small for content.

View Source 
var ErrRequestUnpackInsufficientBuffer = errors.New("given buffer too small for request")

ErrRequestUnpackInsufficientBuffer indicate given buffer too small for request data.

View Source 
var ErrWontImplement = errors.New("will not implement")

ErrWontImplement indicate requested feature will not implement for some reason.

Functions

func UnpackBaggagedEnvelopedMessage added in v0.0.13 

func UnpackBaggagedEnvelopedMessage(b []byte, diagnosisEmitter *DiagnosisEmitter, serviceInstIdent ServiceInstanceIdentifier, operationName string) (spanEmitter *TraceEmitter, m *EnvelopedMessage, remainBytes []byte, err error)

UnpackEnvelopedMessage fetch RawMessage from given buffer and return remain buffer.

Types

type BaggagedMessage added in v0.0.13 

type BaggagedMessage struct {
	EnvelopedMessage

	TraceIdent int32
	SpanIdent  int32
}

func NewBaggagedMessage added in v0.0.13 

func NewBaggagedMessage(spanEmitter *TraceEmitter, rawMsg *EnvelopedMessage) (m *BaggagedMessage)

func UnpackBaggagedMessage added in v0.0.13 

func UnpackBaggagedMessage(b []byte) (m *BaggagedMessage, remainBytes []byte, err error)

UnpackBaggagedMessage fetch RawMessage from given buffer and return remain buffer.

func (*BaggagedMessage) Pack added in v0.0.13 

func (m *BaggagedMessage) Pack(b []byte) (result []byte)

Pack append binary form of RawMessage into given b.

func (*BaggagedMessage) PackedLen added in v0.0.13 

func (m *BaggagedMessage) PackedLen() int

PackedLen return bytes resulted by Pack().

type CertificateProvider 

type CertificateProvider interface {
	// RegisterHostTLSCertificates request certificates for given host names.
	// Should only invoke at maintenance thread in setup stage.
	RegisterHostTLSCertificates(spanEmitter *TraceEmitter, hostNames []string, certSubscriber CertificateSubscriber) (hostTLSCertWatchTrackIdent int, err error)
}

type CertificateSubscriber added in v0.0.3 

type CertificateSubscriber interface {
	// UpdateHostTLSCertificates trigger host TLS update of service.
	// Should only invoke at maintenance thread in setup stage and runtime stage.
	UpdateHostTLSCertificates(waitGroup *sync.WaitGroup, spanEmitter *TraceEmitter, tlsCerts []tls.Certificate) (err error)
}

type DiagnosisEmitter added in v0.0.13 

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

DiagnosisEmitter wrap diagnosis data send and buffering.

func NewDiagnosisEmitter added in v0.0.13 

func NewDiagnosisEmitter(serialPrefix int8, traceBufferSize int) (diag *DiagnosisEmitter)

func (*DiagnosisEmitter) AllocateSerial added in v0.0.13 

func (diag *DiagnosisEmitter) AllocateSerial() (result int32)

func (*DiagnosisEmitter) GetTraceReadChannel added in v0.0.13 

func (diag *DiagnosisEmitter) GetTraceReadChannel() (ch <-chan *qbw1diagrpcgen.TraceRecord)

func (*DiagnosisEmitter) ReleaseTraceReadChannel added in v0.0.13 

func (diag *DiagnosisEmitter) ReleaseTraceReadChannel()

func (*DiagnosisEmitter) StartSpanFromRemoteTrace added in v0.0.13 

func (diag *DiagnosisEmitter) StartSpanFromRemoteTrace(
	remoteTraceIdent int32, remoteSpanIdent int32,
	serviceName ServiceInstanceIdentifier,
	operationName string) (traceEmitter *TraceEmitter)

func (*DiagnosisEmitter) StartTrace added in v0.0.13 

func (diag *DiagnosisEmitter) StartTrace(
	serviceName ServiceInstanceIdentifier,
	operationName,
	traceMessageFmt string, a ...interface{}) (traceEmitter *TraceEmitter)

func (*DiagnosisEmitter) StartTraceWithoutMessage added in v0.0.14 

func (diag *DiagnosisEmitter) StartTraceWithoutMessage(
	serviceName ServiceInstanceIdentifier,
	operationName string) (traceEmitter *TraceEmitter)

type EnvelopedMessage added in v0.0.3 

type EnvelopedMessage struct {
	SourceServiceIdent      int
	DestinationServiceIdent int
	RemainHops              int
	MessageContent          []byte
}

EnvelopedMessage contain message in byte slice.

func MarshalIntoClearEnvelopedMessage added in v0.0.3 

func MarshalIntoClearEnvelopedMessage(
	sourceServiceIdent, destServiceIdent int,
	messageContentType MessageContentType, messageRef proto.Message) (m *EnvelopedMessage, err error)

func MarshalIntoEncryptedEnvelopedMessage added in v0.0.3 

func MarshalIntoEncryptedEnvelopedMessage(
	sourceServiceIdent, destServiceIdent int,
	sharedEncryptKey *[32]byte,
	messageContentType MessageContentType, messageRef proto.Message) (m *EnvelopedMessage, err error)

func NewClearEnvelopedMessage added in v0.0.3 

func NewClearEnvelopedMessage(
	sourceServiceIdent, destServiceIdent int,
	messageContentType MessageContentType, messageContent []byte) (m *EnvelopedMessage)

NewClearEnvelopedMessage create message with message content.

func UnpackEnvelopedMessage added in v0.0.3 

func UnpackEnvelopedMessage(b []byte) (m *EnvelopedMessage, remainBytes []byte, err error)

UnpackEnvelopedMessage fetch RawMessage from given buffer and return remain buffer.

func (*EnvelopedMessage) Decrypt added in v0.0.3 

func (m *EnvelopedMessage) Decrypt(sharedDecryptKey *[32]byte) (err error)

Decrypt message content.

func (*EnvelopedMessage) Digest added in v0.0.3 

func (m *EnvelopedMessage) Digest(d *md5digest.MD5Digest)

Digest checksum message content into given digester. CAUTION: Must decrypt message before invoke this method if message is encrypted. CAUTION: Message size is not checked in this method. CAUTION: Do NOT call this method if .MessageContentType() does not return known type code.

func (*EnvelopedMessage) Encrypt added in v0.0.3 

func (m *EnvelopedMessage) Encrypt(sharedEncryptKey *[32]byte) (err error)

Encrypt message content.

func (*EnvelopedMessage) MessageContentType added in v0.0.3 

func (m *EnvelopedMessage) MessageContentType() (t MessageContentType)

MessageContentType read type code from message content. CAUTION: Must decrypt message before invoke this method if message is encrypted.

func (*EnvelopedMessage) Pack added in v0.0.3 

func (m *EnvelopedMessage) Pack(b []byte) (result []byte)

Pack append binary form of RawMessage into given b.

func (*EnvelopedMessage) PackedLen added in v0.0.3 

func (m *EnvelopedMessage) PackedLen() int

PackedLen return bytes resulted by Pack().

func (*EnvelopedMessage) Unmarshal added in v0.0.3 

func (m *EnvelopedMessage) Unmarshal(ref proto.Message) (err error)

Unmarshal decodes message content into given reference. CAUTION: Must decrypt message before invoke this method if message is encrypted. CAUTION: Message size is not checked in this method. CAUTION: Do NOT call this method if .MessageContentType() does not return known type code.

type MessageContentType 

type MessageContentType uint16

MessageContentType code type of message contents. 

const (
	MessageContentUnknown MessageContentType = iota
	MessageContentKnownServiceIdents
	MessageContentAllocateServiceIdentsRequest
	MessageContentHostCertificateRequest
	MessageContentHostCertificateAssignment
	MessageContentRootCertificateRequest
	MessageContentRootCertificateAssignment
	MessageContentHTTPContentRequest
	MessageContentHTTPContentResponse
	MessageContentHeartbeatPing
	MessageContentHeartbeatPong
	MessageContentHTTPContentLinkClosed
	MessageContentTypeBoundary
)

Type code of message contents.

type MessageDispatcher 

type MessageDispatcher interface {
	// DispatchMessage pass message into message switch.
	DispatchMessage(spanEmitter *TraceEmitter, m *EnvelopedMessage)

	// LinkEstablished notice message switch link is created.
	// Some messages aight sent before notification.
	LinkEstablished(spanEmitter *TraceEmitter)
}

type MessageSender 

type MessageSender interface {
	// Send given message into message switch.
	Send(spanEmitter *TraceEmitter, destServiceIdent int, messageContentType MessageContentType, messageContent proto.Message)

	// ServiceSerialIdentByTextIdent lookup service serial identifier with given text identifier.
	ServiceSerialIdentByTextIdent(textIdent string) (serialIdent int, hasReceiver, ok bool)

	// ServiceProviderRefByTextIdent lookup service provider reference and serial identifier with given text identifier.
	ServiceProviderRefByTextIdent(textIdent string) (serviceProvider ServiceProvider, serialIdent int, hasReceiver, ok bool)
}

type RelayProvider 

type RelayProvider interface {
	// GetServiceInstanceIdentifier return service identifier for this provider.
	GetServiceInstanceIdentifier() (serviceInstIdent ServiceInstanceIdentifier)

	// SetMessageDispatcher should update dispatcher for this instance if relay provider.
	// This method is invoked on register this instance with message switch.
	SetMessageDispatcher(spanEmitter *TraceEmitter, dispatcher MessageDispatcher)

	// EmitMessage send given message through this provider.
	// Will invoke concurrently at operating stage.
	BlockingEmitMessage(spanEmitter *TraceEmitter, envelopedMessage *EnvelopedMessage) (err error)

	// NonblockingEmitMessage send given message through this provider in non-blocking way.
	// Will invoke concurrently at operating stage.
	NonblockingEmitMessage(spanEmitter *TraceEmitter, envelopedMessage *EnvelopedMessage) (emitSuccess bool)
}

type ServiceBase added in v0.0.3 

type ServiceBase struct {
	ServiceInstanceIdent ServiceInstanceIdentifier
}

ServiceBase offer base implementation of services. All services should embed this struct.

func (*ServiceBase) ReceiveMessage added in v0.0.3 

func (s *ServiceBase) ReceiveMessage(spanEmitter *TraceEmitter, rawMessage *EnvelopedMessage) (err error)

ReceiveMessage deliver message into this instance of service provider. The message should decypted before pass into this method.

func (*ServiceBase) RelayProviders added in v0.0.3 

func (s *ServiceBase) RelayProviders() (relayProviders []RelayProvider)

RelayProviders return associated relay providers if available. Return nil if this service provider does not support relay service.

func (*ServiceBase) SetMessageSender added in v0.0.3 

func (s *ServiceBase) SetMessageSender(messageSender MessageSender)

SetMessageSender bind given sender with this instance of service provider.

func (*ServiceBase) Setup added in v0.0.3 

func (s *ServiceBase) Setup(
	serviceInstIdent ServiceInstanceIdentifier,
	diag *DiagnosisEmitter,
	certProvider CertificateProvider) (err error)

Setup prepare provider for operation. Should only invoke at maintenance thread in setup stage.

func (*ServiceBase) Start added in v0.0.3 

func (s *ServiceBase) Start(ctx context.Context, waitGroup *sync.WaitGroup, spanEmitter *TraceEmitter) (err error)

Start service instance for operation. Should only invoke at maintenance thread in setup stage.

func (*ServiceBase) Stop added in v0.0.3 

func (s *ServiceBase) Stop()

Stop service instance,

type ServiceInstanceIdentifier added in v0.0.14 

type ServiceInstanceIdentifier string

type ServiceProvider 

type ServiceProvider interface {
	// Setup prepare provider for operation.
	// Should only invoke at maintenance thread in setup stage.
	Setup(
		serviceInstIdent ServiceInstanceIdentifier,
		diagnosisEmitter *DiagnosisEmitter,
		certProvider CertificateProvider) (err error)

	// Start service instance for operation.
	// Should only invoke at maintenance thread in setup stage.
	Start(ctx context.Context, waitGroup *sync.WaitGroup, spanEmitter *TraceEmitter) (err error)

	// Stop service instance,
	Stop()

	// ReceiveMessage deliver message into this instance of service provider.
	// The message should decypted before pass into this method.
	// Will invoke concurrently at operating stage.
	ReceiveMessage(spanEmitter *TraceEmitter, envelopedMessage *EnvelopedMessage) (err error)

	// SetMessageSender bind given sender with this instance of service provider.
	SetMessageSender(messageSender MessageSender)

	// RelayProviders return associated relay providers if available.
	// Return nil if this service provider does not support relay service.
	RelayProviders() (relayProviders []RelayProvider)
}

ServiceProvider define interface for services.

type ServiceTypeIdentifier 

type ServiceTypeIdentifier int
const (
	ServiceTypeUnknown ServiceTypeIdentifier = iota
	ServiceTypeMessageSwitch
	ServiceTypeAccessProvider
	ServiceTypeHTTPServer
	ServiceTypeHTTPFetcher
	ServiceTypeHTTPEdge
)

func (ServiceTypeIdentifier) String 

func (t ServiceTypeIdentifier) String() string

type StateStore 

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

func NewStateStore 

func NewStateStore(folderPath, serviceType, serviceTextIdent string) (s *StateStore, err error)

func (*StateStore) Marshal 

func (s *StateStore) Marshal(contentIdent string, v interface{}) (err error)

func (*StateStore) Unmarshal 

func (s *StateStore) Unmarshal(contentIdent string, v interface{}) (ok bool, err error)

type TraceEmitter added in v0.0.13 

type TraceEmitter struct {
	TraceIdent      int32
	SpanIdent       int32
	ParentSpanIdent int32
	// contains filtered or unexported fields
}

func (*TraceEmitter) EventError added in v0.0.13 

func (emitter *TraceEmitter) EventError(traceMessageFmt string, a ...interface{})

func (*TraceEmitter) EventInfo added in v0.0.13 

func (emitter *TraceEmitter) EventInfo(traceMessageFmt string, a ...interface{})

func (*TraceEmitter) EventWarning added in v0.0.13 

func (emitter *TraceEmitter) EventWarning(traceMessageFmt string, a ...interface{})

func (*TraceEmitter) FinishSpanCheckBool added in v0.0.13 

func (emitter *TraceEmitter) FinishSpanCheckBool(isSuccess bool)

func (*TraceEmitter) FinishSpanCheckErr added in v0.0.13 

func (emitter *TraceEmitter) FinishSpanCheckErr(err error)

func (*TraceEmitter) FinishSpanFailed added in v0.0.14 

func (emitter *TraceEmitter) FinishSpanFailed(traceMessageFmt string, a ...interface{})

func (*TraceEmitter) FinishSpanFailedErr added in v0.0.13 

func (emitter *TraceEmitter) FinishSpanFailedErr(err error)

func (*TraceEmitter) FinishSpanFailedLogf added in v0.0.14 

func (emitter *TraceEmitter) FinishSpanFailedLogf(traceMessageFmt string, a ...interface{})

func (*TraceEmitter) FinishSpanFailedWithoutMessage added in v0.0.14 

func (emitter *TraceEmitter) FinishSpanFailedWithoutMessage()

func (*TraceEmitter) FinishSpanSuccess added in v0.0.14 

func (emitter *TraceEmitter) FinishSpanSuccess(traceMessageFmt string, a ...interface{})

func (*TraceEmitter) FinishSpanSuccessWithoutMessage added in v0.0.14 

func (emitter *TraceEmitter) FinishSpanSuccessWithoutMessage()

func (*TraceEmitter) LinkBaggagedMessages added in v0.0.13 

func (emitter *TraceEmitter) LinkBaggagedMessages(linkedMessages []*BaggagedMessage)

func (*TraceEmitter) LinkSpanIdents added in v0.0.13 

func (emitter *TraceEmitter) LinkSpanIdents(linkedSpanIdents []*qbw1diagrpcgen.SpanIdent)

func (*TraceEmitter) Logf added in v0.0.13 

func (emitter *TraceEmitter) Logf(traceTypeIdent TraceType, traceMessageFmt string, a ...interface{})

func (*TraceEmitter) StartSpan added in v0.0.13 

func (emitter *TraceEmitter) StartSpan(
	serviceName ServiceInstanceIdentifier,
	operationName,
	traceMessageFmt string, a ...interface{}) (traceEmitter *TraceEmitter)

func (*TraceEmitter) StartSpanWithoutMessage added in v0.0.14 

func (emitter *TraceEmitter) StartSpanWithoutMessage(
	serviceName ServiceInstanceIdentifier,
	operationName string) (traceEmitter *TraceEmitter)

func (*TraceEmitter) TraceSpanIdent added in v0.0.13 

func (emitter *TraceEmitter) TraceSpanIdent() (traceSpanIdent *qbw1diagrpcgen.SpanIdent)

type TraceType added in v0.0.13 

type TraceType int32

TraceType define type for trace type identifier. 

const (
	EmptyTrace TraceType = iota
	TraceStart
	TraceFinish
	TraceSpanStart
	TraceSpanFinish

	EventInfo
	EventWarning
	EventError

	LinkedTrace
)

Identifier values of trace types.

func (TraceType) String added in v0.0.13 

func (i TraceType) String() string

Source Files

View all Source files

Directories

Path Synopsis
accesses
httpaccess
cmd
diag
diag/internal/exporttrace
diag/internal/ping
diag/internal/readtrace
qabalwrapd
contents
httpcontent
gen
qbw1diagrpcgen
qbw1grpcgen
samples
hello-httpd
servers
diagnosissocket
httpserver

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.