grpc

README

PHP Client

Roadrunner GRPC

Compiling proto sample:

protoc --plugin=protoc-gen-php-grpc --php-grpc_out=<OUTPUT DIRECTORY> simple.proto

• protoc-gen-php-grpc plugin can be downloaded from the roadrunner-binary releases page.

Configuration

grpc:
  # GRPC address to listen
  #
  # This option is required
  listen: "tcp://localhost:9001"

  # Proto files to use
  #
  # This option is required. At least one proto file must be specified.
  proto:
      - "proto/test/test.proto"
      - "proto/health/health.proto"

  # GRPC TLS configuration
  #
  # This section is optional
  tls:
    # Path to the key file
    #
    # This option is required
    key: ""

    # Path to the certificate
    #
    # This option is required
    cert: ""

    # Path to the CA certificate
    #
    # This option is optional
    root_ca: ""

    # Client auth type
    #
    # This option is optional. Default value: no_client_certs. Possible values: request_client_cert, require_any_client_cert, verify_client_cert_if_given, require_and_verify_client_cert, no_client_certs
    client_auth_type: ""

  # Maximum send message size
  #
  # This option is optional. Default value: 50 (MB)
  max_send_msg_size: 50

  # Maximum receive message size
  #
  # This option is optional. Default value: 50 (MB)
  max_recv_msg_size: 50

  # MaxConnectionIdle is a duration for the amount of time after which an
  #	idle connection would be closed by sending a GoAway. Idleness duration is
  #	defined since the most recent time the number of outstanding RPCs became
  #	zero or the connection establishment.
  #
  # This option is optional. Default value: infinity.
  max_connection_idle: 0s

  # MaxConnectionAge is a duration for the maximum amount of time a
  #	connection may exist before it will be closed by sending a GoAway. A
  #	random jitter of +/-10% will be added to MaxConnectionAge to spread out
  #	connection storms.
  #
  # This option is optional. Default value: infinity.
  max_connection_age: 0s

  # MaxConnectionAgeGrace is an additive period after MaxConnectionAge after
  #	which the connection will be forcibly closed.
  max_connection_age_grace: 0s

  # MaxConnectionAgeGrace is an additive period after MaxConnectionAge after
  #	which the connection will be forcibly closed.
  #
  # This option is optional: Default value: 10
  max_concurrent_streams: 10

  # After a duration of this time if the server doesn't see any activity it
  #	pings the client to see if the transport is still alive.
  #	If set below 1s, a minimum value of 1s will be used instead.
  #
  # This option is optional. Default value: 2h
  ping_time: 1s

  # After having pinged for keepalive check, the server waits for a duration
  #	of Timeout and if no activity is seen even after that the connection is
  #	closed.
  #
  # This option is optional. Default value: 20s
  timeout: 200s

  # Usual workers pool configuration
  pool:
    num_workers: 2
    max_jobs: 0
    allocate_timeout: 60s
    destroy_timeout: 60

Minimal dependencies:

1. Server plugin for the workers pool.
2. Logger plugin to show log messages.
3. Config plugin to read and populate plugin's configuration.

GRPC worker sample:

<?php

/**
 * Sample GRPC PHP server.
 */

use Service\EchoInterface;
use Spiral\RoadRunner\GRPC\Server;
use Spiral\RoadRunner\Worker;

require __DIR__ . '/vendor/autoload.php';

$server = new Server(null, [
    'debug' => false, // optional (default: false)
]);

$server->registerService(EchoInterface::class, new EchoService());

$server->serve(Worker::create());

Proto file sample:

syntax = "proto3";

package service;
option go_package = "./;test";

service Test {
    rpc Echo (Message) returns (Message) {
    }

    rpc Throw (Message) returns (Message) {
    }

    rpc Die (Message) returns (Message) {
    }

    rpc Info (Message) returns (Message) {
    }

    rpc Ping (EmptyMessage) returns (EmptyMessage) {
    }
}

message Message {
    string msg = 1;
}

message EmptyMessage {
}

message DetailsMessageForException {
    uint64 code = 1;
    string message = 2;
}

Test certificates (including root ca) located here.

Common issues:

1. Registering two services with the same name is not allowed. GRPC server will panic after that.

Documentation

Index

• Constants
• type ClientAuthType
• type Config
  • func (c *Config) EnableTLS() bool
  • func (c *Config) InitDefaults() error
• type HealthCheckServer
  • func NewHeathServer(p *Plugin, log *zap.Logger) *HealthCheckServer
  • func (h *HealthCheckServer) Check(_ context.Context, _ *grpc_health_v1.HealthCheckRequest) (*grpc_health_v1.HealthCheckResponse, error)
  • func (h *HealthCheckServer) RegisterServer(serv *grpc.Server)
  • func (h *HealthCheckServer) SetServingStatus(servingStatus grpc_health_v1.HealthCheckResponse_ServingStatus)
  • func (h *HealthCheckServer) Shutdown()
  • func (h *HealthCheckServer) Watch(_ *grpc_health_v1.HealthCheckRequest, stream grpc_health_v1.Health_WatchServer) error
• type Plugin
  • func (p *Plugin) Init(cfg config.Configurer, log *zap.Logger, server server.Server) error
  • func (p *Plugin) MetricsCollector() []prometheus.Collector
  • func (p *Plugin) Name() string
  • func (p *Plugin) Reset() error
  • func (p *Plugin) Serve() chan error
  • func (p *Plugin) Stop() error
  • func (p *Plugin) Workers() []*process.State
• type TLS

Constants

const (
	RrMode string = "RR_MODE"
)

Types

type ClientAuthType

type ClientAuthType string

const (
	NoClientCert               ClientAuthType = "no_client_cert"
	RequestClientCert          ClientAuthType = "request_client_cert"
	RequireAnyClientCert       ClientAuthType = "require_any_client_cert"
	VerifyClientCertIfGiven    ClientAuthType = "verify_client_cert_if_given"
	RequireAndVerifyClientCert ClientAuthType = "require_and_verify_client_cert"
)

type Config

type Config struct {
	Listen string   `mapstructure:"listen"`
	Proto  []string `mapstructure:"proto"`

	TLS *TLS `mapstructure:"tls"`

	// Env is environment variables passed to the http pool
	Env map[string]string `mapstructure:"env"`

	GrpcPool              *pool.Config  `mapstructure:"pool"`
	MaxSendMsgSize        int64         `mapstructure:"max_send_msg_size"`
	MaxRecvMsgSize        int64         `mapstructure:"max_recv_msg_size"`
	MaxConnectionIdle     time.Duration `mapstructure:"max_connection_idle"`
	MaxConnectionAge      time.Duration `mapstructure:"max_connection_age"`
	MaxConnectionAgeGrace time.Duration `mapstructure:"max_connection_age_grace"`
	MaxConcurrentStreams  int64         `mapstructure:"max_concurrent_streams"`
	PingTime              time.Duration `mapstructure:"ping_time"`
	Timeout               time.Duration `mapstructure:"timeout"`
}

func (*Config) EnableTLS

func (c *Config) EnableTLS() bool

func (*Config) InitDefaults

func (c *Config) InitDefaults() error

type HealthCheckServer

type HealthCheckServer struct {
	grpc_health_v1.HealthCheckRequest
	// contains filtered or unexported fields
}

func NewHeathServer

func NewHeathServer(p *Plugin, log *zap.Logger) *HealthCheckServer

func (*HealthCheckServer) Check

func (h *HealthCheckServer) Check(_ context.Context, _ *grpc_health_v1.HealthCheckRequest) (*grpc_health_v1.HealthCheckResponse, error)

func (*HealthCheckServer) RegisterServer

func (h *HealthCheckServer) RegisterServer(serv *grpc.Server)

func (*HealthCheckServer) SetServingStatus

func (h *HealthCheckServer) SetServingStatus(servingStatus grpc_health_v1.HealthCheckResponse_ServingStatus)

func (*HealthCheckServer) Shutdown

func (h *HealthCheckServer) Shutdown()

func (*HealthCheckServer) Watch

func (h *HealthCheckServer) Watch(_ *grpc_health_v1.HealthCheckRequest, stream grpc_health_v1.Health_WatchServer) error

type Plugin

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

func (*Plugin) Init

func (p *Plugin) Init(cfg config.Configurer, log *zap.Logger, server server.Server) error

func (*Plugin) MetricsCollector

func (p *Plugin) MetricsCollector() []prometheus.Collector

func (*Plugin) Name

func (p *Plugin) Name() string

func (*Plugin) Reset

func (p *Plugin) Reset() error

func (*Plugin) Serve

func (p *Plugin) Serve() chan error

func (*Plugin) Stop

func (p *Plugin) Stop() error

func (*Plugin) Workers

func (p *Plugin) Workers() []*process.State

type TLS

type TLS struct {
	Key      string         `mapstructure:"key"`
	Cert     string         `mapstructure:"cert"`
	RootCA   string         `mapstructure:"root_ca"`
	AuthType ClientAuthType `mapstructure:"client_auth_type"`
	// contains filtered or unexported fields
}