

Protocol Documentation¶

Table of Contents¶

config/bootstrap/bootstrap.proto
- Admin
- Bootstrap
- ConfigSource
- Log
- Log.Output
- Sink
- StaticService
- Stats
- Log.Level
- Log.Output.Type
- Sink.Type
config/hc/hc.proto
config/protocol/redis/redis.proto
config/protocol/protocol.proto
config/service/service.proto
config/service/config.proto
common/instance.proto
- Instance
common/address.proto
- Address
api/discovery.proto
Scalar Value Types

config/bootstrap/bootstrap.proto¶

Admin¶

The admin message is required to configure the administration server.

Field	Type	Label	Description
bind	common.Address		The TCP address that the administration server will listen on, not null.

Bootstrap¶

This message is supplied via '-config' cli flag and act as the root of configuration.

Field	Type	Label	Description
instance	common.Instance		The instance contains the meta information of the current instance.
log	Log		Configuration for log.
stats	Stats		Configuration for stats.
admin	Admin		Configuration for the local administration HTTP server.
static_services	StaticService	repeated	Statically specified services.
dynamic_source_config	ConfigSource		Configuration for dynamic source config.

ConfigSource¶

Configuration for dynamic source config.

Field	Type	Label	Description
endpoint	string		The gRPC endpoint of dynamic source config service, not null.

Log¶

Log config.

Field	Type	Label	Description
level	Log.Level		Logging level
output	Log.Output		Output target configuration, support send log to stdout or syslog, use stdout as default.

Log.Output¶

Field	Type	Label	Description
type	Log.Output.Type		Type of output target.
target	string		Address of server which is required when `SYSLOG` is selected.

Sink¶

Sink is a sink for stats. Each Sink is responsible for writing stats to a backing store.

Field	Type	Label	Description
type	Sink.Type
endpoint	string		Sink endpoint, not empty.

StaticService¶

The wrapper of service config and endpoints.

Field	Type	Label	Description
name	string		The name of service.
config	service.Config		The proxy strategy of service.
endpoints	service.Endpoint	repeated	The endpoints of service. Need at least one endpoint.

Stats¶

Stats config.

Field	Type	Label	Description
sinks	Sink	repeated	Optional set of stats sinks.

Log.Level¶

Name	Number	Description
INFO	0	Print base messages during running. This is in addition to warnings and errors.
DEBUG	-1	Print everything, including debugging information.
WARING	1	Print all warnings and errors.
ERROR	2	Print all errors.
QUIET	3	Print nothing.

Log.Output.Type¶

Name	Number	Description
STDOUT	0	stdout
SYSLOG	1	syslog

Sink.Type¶

Sink type

Name	Number	Description
UNKNOWN	0
STATSD	1	statsd

Top

config/hc/hc.proto¶

ATCPChecker¶

ATCP checker config.

Field	Type	Label	Description
action	ATCPChecker.Action	repeated	List of actions. All actions will execute during the health check, if one of the actions fails, this health check will be considered as failed. Need at least one action.

ATCPChecker.Action¶

Action represents a set of requests from Samaritan to the server and what the expected server returns.

Field	Type	Label	Description
send	bytes		This is used to send a data along with a connection opening.
expect	bytes		Expecting content returned from the server.

HealthCheck¶

Configuration of health check.

Field	Type	Description
interval	google.protobuf.Duration	The interval between two consecutive health checks. Must be greater than 0s.
timeout	google.protobuf.Duration	The timeout when doing a health check. Must be greater than 0s.
fall_threshold	uint32	A server will be considered as dead after # consecutive unsuccessful health checks. Must be greater than 0.
rise_threshold	uint32	A server will be considered as operational after # consecutive successful health checks. Must be greater than 0.
tcp_checker	TCPChecker
atcp_checker	ATCPChecker
mysql_checker	MySQLChecker
redis_checker	RedisChecker

MySQLChecker¶

MySQL checker config.

Field	Type	Label	Description
username	string		MySQL server username, not null.

RedisChecker¶

Redis checker config.

Field	Type	Label	Description
password	string		Redis server password, if the password is not empty, the AUTH command will be sent before the PING command.

TCPChecker¶

TCP checker config.

Top

config/protocol/redis/redis.proto¶

Compression¶

Configuration of compression.

Field	Type	Description
enable	bool	Switch of compress, default is off. NOTE: Uncompress will always work.
algorithm	Compression.Algorithm	Compression algorithm used in compression filter.
threshold	uint32	Value will be ignored when byte length of value is less than the threshold, must be greater than 0.

Compression.Algorithm¶

Name	Number	Description
SNAPPY	0

ReadStrategy¶

Strategy of a read only command.

Name	Number	Description
MASTER	0	Read from master nodes.
REPLICA	1	Read from replica nodes.
BOTH	2	Read from all nodes.

Top

config/protocol/protocol.proto¶

MySQLOption¶

MySQL protocol option.

RedisOption¶

Redis protocol option.

Field	Type	Label	Description
read_strategy	redis.ReadStrategy		Strategy of a read only command.
compression	redis.Compression		Configuration of compression.

TCPOption¶

TCP protocol option.

Protocol¶

Protocol enum.

Name	Number	Description
UNKNOWN	0
TCP	1	TCP
MySQL	2	MySQL
Redis	3	Redis

Top

config/service/service.proto¶

Endpoint¶

Endpoint represents an endpoint of service.

Field	Type	Description
address	common.Address	Address of endpoint, must be set.
state	Endpoint.State	Healthy state of endpoint. When state is DOWN, this host will not be selected for load balancing.
type	Endpoint.Type	Type of endpoints. When all hosts whose type is main are in the DOWN state, the host whose type is backup will be selected.

Service¶

Service represents a service.

Field	Type	Label	Description
name	string		Name of service.

Endpoint.State¶

Name	Number	Description
UP	0	healthy
DOWN	1	unhealthy
UNKNOWN	2	unknown

Endpoint.Type¶

Name	Number	Description
MAIN	0	main
BACKUP	1	backup

Top

config/service/config.proto¶

Config¶

Configuration of service, contains configuration information required for the processor to run.

Field	Type	Description
listener	Listener	Listener config, must be set.
health_check	hc.HealthCheck	Health check will be disabled when not defined.
connect_timeout	google.protobuf.Duration	The maximum time to wait for a connection attempt to a server to succeed, default is 3s.
idle_timeout	google.protobuf.Duration	The maximum inactivity time on the client side, default is 10min.
lb_policy	LoadBalancePolicy
protocol	protocol.Protocol	Protocol of service, can not be UNKNOWN.
tcp_option	protocol.TCPOption
redis_option	protocol.RedisOption
mysql_option	protocol.MySQLOption

Listener¶

Listener configuration.

Field	Type	Label	Description
address	common.Address		The address that the listener should listen on, must be set.
connection_limit	uint32		The limit of connections, new connections that exceed this value are immediately be closed. Default value is 0 that the limit will be disable.

LoadBalancePolicy¶

Load balance policy.

Name	Number	Description
ROUND_ROBIN	0	RoundRobin
LEAST_CONNECTION	1	LeastConnection
RANDOM	2	Random
CLUSTER_PROVIDED	3	Provided by redis cluster

Top

common/instance.proto¶

Instance¶

Field	Type	Description
id	string	The id of this instance, if id is not define, it will generate by ip and admin port.
version	string	Version of this instance running now. This field is automatically populated by Samaritan does not require to specify by user.
belong	string	The service name which this instance belongs to. It's required when you want to change the behavior of Sam at runtime, such as update proxy policy, update service endpoints, etc. If two instances belong to the same service, it will be treated in one group.

Top

common/address.proto¶

Address¶

Field	Type	Label	Description
ip	string		IP address, IPv4 or IPv6.
port	uint32		Port, [0, 65535].

Top

api/discovery.proto¶

DependencyDiscoveryRequest¶

Field	Type	Label	Description
instance	common.Instance		Meta information of the current instance.

DependencyDiscoveryResponse¶

Field	Type	Label	Description
added	service.Service	repeated	Added service.
removed	service.Service	repeated	Removed service.

SvcConfigDiscoveryRequest¶

Field	Type	Label	Description
svc_names_subscribe	string	repeated	All service names that need to subscribe.
svc_names_unsubscribe	string	repeated	All service names that need to unsubscribe.

SvcConfigDiscoveryResponse¶

Field	Type	Label	Description
updated	SvcConfigDiscoveryResponse.UpdatedEntry	repeated	Update of configuration.

SvcConfigDiscoveryResponse.UpdatedEntry¶

Field	Type	Label	Description
key	string
value	service.Config

SvcEndpointDiscoveryRequest¶

Field	Type	Label	Description
svc_names_subscribe	string	repeated	All service names that need to subscribe.
svc_names_unsubscribe	string	repeated	All service names that need to unsubscribe.

SvcEndpointDiscoveryResponse¶

Field	Type	Label	Description
svc_name	string		Name of service which endpoints had updated.
added	service.Endpoint	repeated	Added endpoints.
removed	service.Endpoint	repeated	Removed endpoints.

DiscoveryService¶

DiscoveryService is a service which is used to discover service, service config and service endpoints.

Method Name	Request Type	Response Type
StreamDependencies	DependencyDiscoveryRequest	DependencyDiscoveryResponse stream
StreamSvcConfigs	SvcConfigDiscoveryRequest stream	SvcConfigDiscoveryResponse stream
StreamSvcEndpoints	SvcEndpointDiscoveryRequest stream	SvcEndpointDiscoveryResponse stream

Scalar Value Types¶

.proto Type	Notes	C++ Type	Java Type	Python Type
double		double	double	float
float		float	float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long
uint32	Uses variable-length encoding.	uint32	int	int/long
uint64	Uses variable-length encoding.	uint64	long	int/long
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long
sfixed32	Always four bytes.	int32	int	int
sfixed64	Always eight bytes.	int64	long	int/long
bool		bool	boolean	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str