mgrpc

Documentation

Overview

Copyright (c) 2014-2019 Cesanta Software Limited All rights reserved

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright (c) 2014-2019 Cesanta Software Limited All rights reserved

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright (c) 2014-2019 Cesanta Software Limited All rights reserved

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• type ConnectOption
  • func ClientCert(cert *tls.Certificate) ConnectOption
  • func ClientCertFiles(certFile, keyFile string) ConnectOption
  • func CodecOptions(co codec.Options) ConnectOption
  • func CompatArgs(enable bool) ConnectOption
  • func LocalID(localID string) ConnectOption
  • func Reconnect(enable bool) ConnectOption
  • func SendPSK(psk string) ConnectOption
  • func TlsConfig(tlsConfig *tls.Config) ConnectOption
  • func Tracing(enable bool) ConnectOption
  • func UseHTTPPost() ConnectOption
  • func UseWebSocket() ConnectOption
  • func VerifyServerWith(ca *x509.CertPool) ConnectOption
  • func VerifyServerWithCAsFromFile(file string) ConnectOption
• type ErrorResponse
  • func (e ErrorResponse) Error() string
• type GetCredsCallback
• type HTTPListenerConfig
• type Handler
• type ListenOption
  • func ListenerTracing(enable bool) ListenOption
  • func ServerCert(cert *tls.Certificate) ListenOption
  • func ServerCertFiles(certFile, keyFile string) ListenOption
  • func VerifyClientsWith(pool *x509.CertPool) ListenOption
  • func VerifyClientsWithCAsFromFile(file string) ListenOption
• type ListenerConfig
  • func ListenerConfigFromURL(urlStr string) (ListenerConfig, error)
• type MgRPC
  • func New(ctx context.Context, connectAddr string, opts ...ConnectOption) (MgRPC, error)
  • func Serve(ctx context.Context, c codec.Codec) MgRPC
• type TCPListenerConfig
• type TLSConfig

Types

type ConnectOption

type ConnectOption func(*connectOptions) error

ConnectOption is an optional argument to Instance.Connect which affects the behaviour of the connection.

func ClientCert

func ClientCert(cert *tls.Certificate) ConnectOption

ClientCert specifies the client certificate chain to supply to the server and enables TLS.

func ClientCertFiles

func ClientCertFiles(certFile, keyFile string) ConnectOption

ClientCertFiles will load certificate and key from the specified files to present to the server and enables TLS. If file names are empty, this option does nothing.

func CodecOptions

func CodecOptions(co codec.Options) ConnectOption

func CompatArgs

func CompatArgs(enable bool) ConnectOption

func LocalID

func LocalID(localID string) ConnectOption

LocalID specifies mgrpc id of the local node

func Reconnect

func Reconnect(enable bool) ConnectOption

func SendPSK

func SendPSK(psk string) ConnectOption

SendPSK sets the preshared-key for the connection.

func TlsConfig

func TlsConfig(tlsConfig *tls.Config) ConnectOption

func Tracing

func Tracing(enable bool) ConnectOption

Tracing enables the RPC tracing functionality.

func UseHTTPPost

func UseHTTPPost() ConnectOption

UseHTTPPost instructs RPC to use HTTP POST requests to send commands.

func UseWebSocket

func UseWebSocket() ConnectOption

UseWebSocket instructs RPC to create a WebSocket connection.

func VerifyServerWith

func VerifyServerWith(ca *x509.CertPool) ConnectOption

VerifyServerWith specifies the pool of CA certificates to use for validating server's certificate.

func VerifyServerWithCAsFromFile

func VerifyServerWithCAsFromFile(file string) ConnectOption

VerifyServerWithCAsFromFile is a wrapper for VerifyServerWith that reads CA certificates from file.

type ErrorResponse

type ErrorResponse struct {
	// Status is the numerical status code.
	Status int
	// Msg is a human-readable description of the error.
	Msg string
}

ErrorResponse is an error type for failed commands. Intended for use by wrappers around Call() method, like ones generated by clubbygen.

func (ErrorResponse) Error

func (e ErrorResponse) Error() string

type GetCredsCallback

type GetCredsCallback func() (username, passwd string, err error)

type HTTPListenerConfig

type HTTPListenerConfig struct {
	// Accept RPC frames in POST requests.
	EnablePOST bool `yaml:"enable_post,omitempty"`
	// Allow upgrading to a WebSocket connection.
	// Note: Currently both POST and WebSocket cannot be used on the same listener.
	EnableWebSocket bool `yaml:"enable_websocket,omitempty"`
	// Cloud host base. If set, then for REST-like requests destination can be
	// specified in the Host header, and will be derived by stripping this suffix.
	CloudHost string `yaml:"cloud_host,omitempty"`
}

HTTPListenerConfig configures the HTTP and WebSocket listener.

type Handler

type Handler func(MgRPC, *frame.Frame) *frame.Frame

type ListenOption

type ListenOption func(*ListenerConfig)

ListenOption implements the option pattern for the Listen function

func ListenerTracing

func ListenerTracing(enable bool) ListenOption

ListenerTracing enables the RPC tracing functionality.

func ServerCert

func ServerCert(cert *tls.Certificate) ListenOption

ServerCert specifies the certificate to present to remote peers and enables TLS.

func ServerCertFiles

func ServerCertFiles(certFile, keyFile string) ListenOption

ServerCertFiles will load certificate and key from the specified files to be used by the server and enables TLS. If file names are empty, this option does nothing.

func VerifyClientsWith

func VerifyClientsWith(pool *x509.CertPool) ListenOption

VerifyClientsWith specifies the pool of CA certificates to use for validating client certificates.

func VerifyClientsWithCAsFromFile

func VerifyClientsWithCAsFromFile(file string) ListenOption

VerifyClientsWithCAsFromFile is a wrapper for VerifyClientsWith that reads CA certificates from file.

type ListenerConfig

type ListenerConfig struct {
	// Address suitable for net.Listener (currently only TCP).
	Addr string `yaml:"addr"`
	// If present, connections will be wrapped in a TLS wrapper and this field
	// specifies the configuration.
	TLS *TLSConfig `yaml:"tls,omitempty"`

	// TCP listener sends RPC frames over plain TCP.
	TCP *TCPListenerConfig `yaml:"tcp,omitempty"`
	// HTTP listener uses HTTP POST requests to send RPC frames.
	// HTTP listener also supports WebSocket connections.
	HTTP *HTTPListenerConfig `yaml:"http,omitempty"`

	EnableTracing bool `yaml:"enable_tracing"`
}

ListenerConfig specifies a listener that receives RPC connections.

func ListenerConfigFromURL

func ListenerConfigFromURL(urlStr string) (ListenerConfig, error)

ListenerConfigFromURL offers a quick way to create ListenerConfig from URL, e.g. http://:8081.

type MgRPC

type MgRPC interface {
	Call(
		ctx context.Context, dst string, cmd *frame.Command, getCreds GetCredsCallback,
	) (*frame.Response, error)
	AddHandler(method string, handler Handler)
	Disconnect(ctx context.Context) error
	IsConnected() bool
	SetCodecOptions(opts *codec.Options) error
}

func New

func New(ctx context.Context, connectAddr string, opts ...ConnectOption) (MgRPC, error)

func Serve

func Serve(ctx context.Context, c codec.Codec) MgRPC

type TCPListenerConfig

type TCPListenerConfig struct {
}

TCPListenerConfig is a TCP listener configuration.

type TLSConfig

type TLSConfig struct {
	// Certificate and key to be used by the server. Either a parsed Cert or file names for both
	// must be provided. It's ok to have certificate and key in the same file.
	Cert     *tls.Certificate `yaml:"-"`
	CertFile string           `yaml:"cert_file,omitempty"`
	KeyFile  string           `yaml:"key_file,omitempty"`
	// CA certificates to use to validate clients.
	// This enables requesting client certificate during handshake, which is off by default.
	// A pre-existing pool or a file to load from can be specified (but not both).
	ClientCAPool     *x509.CertPool `yaml:"-"`
	ClientCAPoolFile string         `yaml:"client_ca_pool_file,omitempty"`
}

TLSConfig configures the TLS listener wrapper.