protocol

package
v0.3.0-beta Latest Latest
Warning

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

 Go to latest Published: Apr 16, 2018 License: MIT Imports: 16 Imported by: 0

README

Protocol Specification Version 1.0 (Draft)

Summary

This binary protocol is for the purpose of communication with goapptrace server and trace target process. All data can split to unit called the packet. This protocol exchange packet's through TCP. Unix socket supports is planned, but it is not supported currently.

Packet Specification

Packet is unit of encode/decode. Packet MUST encode to binary by *Packet.Marshal() method and *Packet.Unmarshal() method. Packet can classable to HelloPacket type, HeaderPacket type and DataPacket type.

  • HeaderPacket notify about a DataPacket and HelloPacket of packet type and packet length. Client and Server MUST send that packet before each data packet sends.
  • HelloPacket only use when negotiation process. That is two types of ClientHelloPacket and ServerHelloPacket. Those packet is for the purpose of sends the protocol version etc. to the partner.
  • DataPacket is ... see the source code.

For more information about those packet fields, see the source code in packet.go. For usage, see Protocol Negotiation Sequence section.

Protocol Version Specification

Protocol version MUST have only major version and minor version. String expression of protocol version is major version and minor version splitted by "." like "[major].[minor]".

Example: When major version is 1 and minor version is 23, String expression is "1.23"

Protocol Negotiation Sequence

  1. Client open TCP socket with the server.
  2. Client sends a packet of ClientHelloPacket to the server. Server receives a packet from client, and checks protocol version. If any errors occurs, server can close TCP socket immediately.
  3. Server sends a packet of ServerHelloPacket to the server. Client receives a packet from server, and checks checks it. If any errors occurs, client can close TCP socket immediately.
  4. The negotiation process will be succeeded. Client and Server are sends any packet to the partner any time.
  5. If Client/Server want to close this TCP session, SHOULD send a ShutdownPacket to a partner before close this TCP session.
          [Negotiation Flow]
Client                          Server

  +                                +
  |                                |
  |   [2] ClientHelloPacket        |
  |                                |
  +----------------------------->  |
  |                                |
  |   [3] ServerHelloPacket        |
  |                                |
  |   <----------------------------+
  |                                |
  |   (Negotiation Complete)       |
  |   [4] HeaderPacket/DataPacket  |
  |   can send any time.           |
  |                                |
  |   <------------------------->  |
  |                                |
  |   [5] ShutdownPacket           |
  |   (EX: close from client)      |
  |                                |
  +----------------------------->  |
  |                                |
  |   [6] We SHOULD close this     |
  +   TCP session.                 +

Documentation

Index

Constants

View Source 
const (
	// 送信バッファに溜まっているパケットを強制的に排出する間隔。
	DefaultRefreshInterval = 100 * time.Millisecond

	// 最も頻繁に送受信されるパケットの最大サイズ。
	// client側はこれらのパケットをバッファリングしており、非同期送信ができる。
	DefaultMaxSmallPacketSize = 1 << 20 //1 MiB
	// 送受信可能なパケットの最大サイズ。
	// このパケットはバッファリングされず、送信完了までブロックする。
	// パフォーマンス低下の原因になる。
	DefaultMaxLargePacketSize = 100 * 1 << 20 // 100MiB

	// 送信キューに滞留可能なパケット数
	DefaultSendListLen     = 30
	DefaultRecvBufInitSize = 1 << 20       // 1MiB
	DefaultRecvBufMaxSize  = 100 * 1 << 20 // 100MiB
	DefaultSendBufInitSize = 1 << 20       // 1MiB
	DefaultSendBufMaxSize  = 100 * 1 << 20 // 100MiB
)
View Source 
const (
	DefaultMaxRetries = 10
	MinWaitTime       = 10 * time.Millisecond
)
View Source 
const (
	ClientHelloPacketType
	ServerHelloPacketType
	LogPacketType
	PingPacketType
	ShutdownPacketType
	StartTraceCmdPacketType
	StopTraceCmdPacketType
	SymbolPacketType
	RawFuncLogPacketType
)
View Source 
const (
	ProtocolVersion = "1"

	// パケットをエンコードすることにより増加するバイト数。
	// 内約は、パケットサイズ(4byte)+HeaderPacket(1byte)
	PacketHeaderSize = 5
)
View Source 
const (
	DefaultTCPPort = 8600
	MaxListenTries = 100
)
View Source 
const (
	DefaultTimeout      = 10 * time.Second
	DefaultPingInterval = 3 * time.Second
)

Variables

View Source 
var (
	InvalidProtocolError = errors.New("invalid protocol")
)

Functions

This section is empty.

Types

type BufferOption 

type BufferOption struct {
	// 送信バッファに溜まっているパケットを強制的に送信する間隔。
	RefreshInterval time.Duration

	MaxSmallPacketSize int
	MaxLargePacketSize int

	// xtcp関連
	Xtcp XtcpBufferOption
}

func (*BufferOption) SetDefault 

func (opt *BufferOption) SetDefault()

type Client 

type Client struct {
	// Addr is "tcp://host:port"
	// 現在は、"unix:///path/to/socket/file" 形式のアドレスはサポートしていない。
	Addr    string
	Handler ClientHandler

	PID          uint64
	AppName      string
	Host         string
	Secret       string
	PingInterval time.Duration
	MaxRetries   int
	BufferOpt    BufferOption
	// contains filtered or unexported fields
}

ログサーバとの通信を行うクライアントの実装。 再接続機能が無いので、この実装を使用する側で適宜再接続を行うこと。

func (*Client) Close 

func (c *Client) Close() error

func (*Client) Init 

func (c *Client) Init()

func (*Client) OnEvent 

func (c *Client) OnEvent(et xtcp.EventType, conn *xtcp.Conn, p xtcp.Packet)

p will be nil when event is EventAccept/EventConnected/EventClosed

func (*Client) Send 

func (c *Client) Send(pkt xtcp.Packet) error

Send sends a packet asynchronously. pkt is marshalled immediately. Caller can be reuse pkt after return this function.

func (*Client) SendLarge 

func (c *Client) SendLarge(largePkt xtcp.Packet) error

SendLarge sends a large packet.

func (*Client) Serve 

func (c *Client) Serve() error

Serve connects to the server and serve. this method is block until disconnected.

func (*Client) WaitNegotiation 

func (c *Client) WaitNegotiation()

WaitNegotiation wait for negotiation to be finish

type ClientHandler 

type ClientHandler struct {
	Connected    func()
	Disconnected func()

	Error func(error)

	Shutdown   func(*ShutdownPacket)
	StartTrace func(*StartTraceCmdPacket)
	StopTrace  func(*StopTraceCmdPacket)
}

クライアントで発生したイベントのイベントハンドラ。 不要なフィールドはnilにすることが可能。

type ClientHelloPacket 

type ClientHelloPacket struct {
	// Process ID
	// 本来はint64にするべきだと思うが、encoderがuint64にしか対応していないため、uint64にした。
	PID uint64
	// Application Name
	AppName string
	// トレーサが動いているHost name
	Host            string
	ClientSecret    string
	ProtocolVersion string
}

func (*ClientHelloPacket) Marshal 

func (p *ClientHelloPacket) Marshal(buf []byte) int64

func (ClientHelloPacket) String 

func (p ClientHelloPacket) String() string

func (*ClientHelloPacket) Unmarshal 

func (p *ClientHelloPacket) Unmarshal(buf []byte) int64

type ConnHandler 

type ConnHandler struct {
	Connected    func(pkt *ClientHelloPacket)
	Disconnected func()

	Error func(err error)

	Symbols    func(diff *types.SymbolsData)
	RawFuncLog func(funclog *types.RawFuncLog)
}

TCPコネクションで発生したイベントのハンドラ。 1つのコネクションごとにハンドラが作成されるため、handlerの中でconnection localな変数を保持しても構わない。 不要なフィールドはnilにすることが可能。

func (ConnHandler) SetDefault 

func (sh ConnHandler) SetDefault(fn func(field string)) ConnHandler

SetDefault sets "fn" to all nil fields.

type ConnID 

type ConnID int64

TCPコネクションを一意に識別するID

type DirectWritable 

type DirectWritable interface {
	WriteTo(w io.Writer) (int64, error)
}

type HeaderPacket 

type HeaderPacket struct {
	PacketType PacketType
}

func (*HeaderPacket) Marshal 

func (p *HeaderPacket) Marshal(buf []byte) int64

func (HeaderPacket) String 

func (p HeaderPacket) String() string

func (*HeaderPacket) Unmarshal 

func (p *HeaderPacket) Unmarshal(buf []byte) int64

type LogPacket 

type LogPacket struct{}

func (*LogPacket) Marshal 

func (p *LogPacket) Marshal(buf []byte) int64

func (LogPacket) String 

func (p LogPacket) String() string

func (*LogPacket) Unmarshal 

func (p *LogPacket) Unmarshal(buf []byte) int64

type Marshalable 

type Marshalable interface {
	Marshal(buf []byte) int64
	Unmarshal(buf []byte) int64
}

type MergePacket 

type MergePacket struct {
	Proto      ProtoInterface
	BufferSize int
	// contains filtered or unexported fields
}

MergePacket can merge several short packets. It helps to increase performance by reduce short packets.

func (*MergePacket) Len 

func (p *MergePacket) Len() int

func (*MergePacket) Merge 

func (p *MergePacket) Merge(packet xtcp.Packet)

func (*MergePacket) Reset 

func (p *MergePacket) Reset()

func (*MergePacket) String 

func (p *MergePacket) String() string

func (*MergePacket) WriteTo 

func (p *MergePacket) WriteTo(w io.Writer) (int64, error)

type PacketSender 

type PacketSender interface {
	Send(p xtcp.Packet) error
	Stop(mode xtcp.StopMode)
}

type PacketType 

type PacketType uint8

func (PacketType) Marshal 

func (p PacketType) Marshal(buf []byte) int64

func (*PacketType) Unmarshal 

func (p *PacketType) Unmarshal(buf []byte) int64

type PingPacket 

type PingPacket struct{}

func (*PingPacket) Marshal 

func (p *PingPacket) Marshal(buf []byte) int64

func (PingPacket) String 

func (p PingPacket) String() string

func (*PingPacket) Unmarshal 

func (p *PingPacket) Unmarshal(buf []byte) int64

type Proto 

type Proto struct{}

Message: [size int32] [hp HeaderPacket] [p xtcp.Packet] size = hp.size() + p.size()

func (Proto) Pack 

func (pr Proto) Pack(p xtcp.Packet) ([]byte, error)

このメソッドはどこからも使用されていないため、実装していない。 もしこのメソッドを呼び出すと、panicする。

func (Proto) PackSize 

func (pr Proto) PackSize(p xtcp.Packet) int

このメソッドはどこからも使用されていないため、実装していない。 もしこのメソッドを呼び出すと、panicする。

func (Proto) PackTo 

func (pr Proto) PackTo(p xtcp.Packet, w io.Writer) (int, error)

func (Proto) PackToByteSlice 

func (pr Proto) PackToByteSlice(p xtcp.Packet, buf []byte) int64

func (Proto) Unpack 

func (pr Proto) Unpack(b []byte) (xtcp.Packet, int, error)

type ProtoInterface 

type ProtoInterface interface {
	xtcp.Protocol
	PackToByteSlice(p xtcp.Packet, buf []byte) int64
}

type RawFuncLogPacket 

type RawFuncLogPacket struct {
	FuncLog *types.RawFuncLog
}

func (*RawFuncLogPacket) Marshal 

func (p *RawFuncLogPacket) Marshal(buf []byte) int64

func (RawFuncLogPacket) String 

func (p RawFuncLogPacket) String() string

func (*RawFuncLogPacket) Unmarshal 

func (p *RawFuncLogPacket) Unmarshal(buf []byte) int64

type Server 

type Server struct {
	// "unix:///path/to/socket/file" or "tcp://host:port"
	Addr       string
	NewHandler func(id ConnID, conn PacketSender) *ConnHandler

	AppName      string
	Secret       string
	PingInterval time.Duration
	BufferOpt    BufferOption
	// contains filtered or unexported fields
}

トレース対象との通信を行うサーバ。 プロトコルの詳細は、README.mdに記載している。

Usage: 

srv.Listen()
go srv.Serve()

// wait for stop signal
time.Sleep(time.Second)

srv.Close()
srv.Wait()

func (*Server) ActualAddr 

func (s *Server) ActualAddr() string

func (*Server) Close 

func (s *Server) Close() error

func (*Server) Listen 

func (s *Server) Listen() error

func (*Server) OnEvent 

func (s *Server) OnEvent(et xtcp.EventType, conn *xtcp.Conn, p xtcp.Packet)

func (*Server) Serve 

func (s *Server) Serve()

func (*Server) Wait 

func (s *Server) Wait()

type ServerConn 

type ServerConn struct {
	ID      ConnID
	Conn    *xtcp.Conn
	Handler *ConnHandler
	// contains filtered or unexported fields
}

Serverが管理しているコネクションの状態を管理と、イベントハンドラの呼び出しを行う。

func (*ServerConn) OnEvent 

func (s *ServerConn) OnEvent(et xtcp.EventType, conn *xtcp.Conn, p xtcp.Packet)

p will be nil when event is EventAccept/EventConnected/EventClosed

func (*ServerConn) Send 

func (s *ServerConn) Send(p xtcp.Packet) error

func (*ServerConn) Stop 

func (s *ServerConn) Stop(mode xtcp.StopMode)

type ServerHelloPacket 

type ServerHelloPacket struct {
	ProtocolVersion string
}

func (*ServerHelloPacket) Marshal 

func (p *ServerHelloPacket) Marshal(buf []byte) int64

func (ServerHelloPacket) String 

func (p ServerHelloPacket) String() string

func (*ServerHelloPacket) Unmarshal 

func (p *ServerHelloPacket) Unmarshal(buf []byte) int64

type ShutdownPacket 

type ShutdownPacket struct{}

func (*ShutdownPacket) Marshal 

func (p *ShutdownPacket) Marshal(buf []byte) int64

func (ShutdownPacket) String 

func (p ShutdownPacket) String() string

func (*ShutdownPacket) Unmarshal 

func (p *ShutdownPacket) Unmarshal(buf []byte) int64

type SizePredictable 

type SizePredictable interface {
	// PacketSize returns encoded byte size.
	PacketSize() int64
}

type StartTraceCmdPacket 

type StartTraceCmdPacket struct {
	FuncName string
}

func (*StartTraceCmdPacket) Marshal 

func (p *StartTraceCmdPacket) Marshal(buf []byte) int64

func (StartTraceCmdPacket) String 

func (p StartTraceCmdPacket) String() string

func (*StartTraceCmdPacket) Unmarshal 

func (p *StartTraceCmdPacket) Unmarshal(buf []byte) int64

type StopTraceCmdPacket 

type StopTraceCmdPacket struct {
	FuncName string
}

func (*StopTraceCmdPacket) Marshal 

func (p *StopTraceCmdPacket) Marshal(buf []byte) int64

func (StopTraceCmdPacket) String 

func (p StopTraceCmdPacket) String() string

func (*StopTraceCmdPacket) Unmarshal 

func (p *StopTraceCmdPacket) Unmarshal(buf []byte) int64

type SymbolPacket 

type SymbolPacket struct {
	types.SymbolsData
}

func (*SymbolPacket) Marshal 

func (p *SymbolPacket) Marshal(buf []byte) int64

func (*SymbolPacket) PacketSize 

func (p *SymbolPacket) PacketSize() int64

func (SymbolPacket) String 

func (p SymbolPacket) String() string

func (*SymbolPacket) Unmarshal 

func (p *SymbolPacket) Unmarshal(buf []byte) int64

type XtcpBufferOption 

type XtcpBufferOption struct {
	SendListLen     int
	RecvBufInitSize int
	SendBufInitSize int
	RecvBufMaxSize  int
	SendBufMaxSize  int
}

func (*XtcpBufferOption) Set 

func (opt *XtcpBufferOption) Set(o *xtcp.Options)

func (*XtcpBufferOption) SetDefault 

func (opt *XtcpBufferOption) SetDefault()

Source Files

View all Source files

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.