README
¶
go-resp
go-resp is a fast and simple, barebones RESP (Redis serialization protocol) parser and serializer for Go.
Installing
go get -u github.com/Fusl/go-resp
Usage
resp.NewServer() accepts a io.ReadWriter, io.ReadWriteCloser, or net.Conn and returns a resp.Server which can be used to read and write RESP messages.
Reading
Every Server instance has a Next() method which reads the next RESP message from the connection. The method returns a [][]byte slice containing the RESP message and an error. Care must be taken when reading the message as the slice and the underlying byte slices are reused for every call to Next(). If in doubt, copy the slice and every byte slice it contains to a newly allocated slice and byte slices.
Writing
Every Server instance has various write methods for writing RESP messages to the connection. The methods are named after the RESP message type they write. By default, messages are written in RESP3 compatible format. Calling SetRESP2Compat(true) on a Server instance will make it write messages in RESP2 compatible format instead, even when calling RESP3 methods such as WriteMapBytes() which are not available in RESP2 and therefore converted to arrays.
See the go-resp package documentation for a list of all available write methods and how to use them.
Concurrency
Reading or writing is not thread-safe and should not be done concurrently. You may read with Next() in one goroutine and write with Write() in another goroutine, but you should not call Next() or Write() concurrently.
Example
See example/example.go for a simple example server.
Benchmarks
Benchmark information
Hardware
- CPU: Intel Core i9-13900KF @ 5.5GHz
- RAM: 4x 32GB DDR4 @ 3200MHz
Benchmark command
$ redis-benchmark -p <port> -c <clients> -P <numreq> -n 100000000 ping
Standard Redis Server
$ redis-server --port 6379 --appendonly no --save ''
| -c | -P | Throughput | latency | min | p50 | p95 | p99 | max |
|---|---|---|---|---|---|---|---|---|
| 1 | 1 | 161,421 | 0.004 | 0.000 | 0.007 | 0.007 | 0.007 | 0.303 |
| 1 | 1000 | 6,930,488 | 0.112 | 0.104 | 0.119 | 0.119 | 0.119 | 0.279 |
| 10 | 1000 | 9,683,355 | 0.935 | 0.112 | 0.935 | 1.007 | 1.015 | 1.679 |
go-resp example server (GOMAXPROCS=8)
$ GOMAXPROCS=8 go run ./example/example.go
| -c | -P | Throughput | Increase | latency | min | p50 | p95 | p99 | max |
|---|---|---|---|---|---|---|---|---|---|
| 1 | 1 | 169,964 | +5.29% | 0.004 | 0.000 | 0.007 | 0.007 | 0.007 | 0.311 |
| 1 | 1000 | 11,774,402 | +69.89% | 0.052 | 0.048 | 0.055 | 0.055 | 0.055 | 0.159 |
| 10 | 1000 | 31,318,508 | +223.43% | 0.188 | 0.048 | 0.183 | 0.271 | 0.319 | 0.567 |
go-resp example server (GOMAXPROCS=1)
$ GOMAXPROCS=1 go run ./example/example.go
| -c | -P | Throughput | Increase | latency | min | p50 | p95 | p99 | max |
|---|---|---|---|---|---|---|---|---|---|
| 1 | 1 | 169,330 | +4.90% | 0.004 | 0.000 | 0.007 | 0.007 | 0.007 | 0.271 |
| 1 | 1000 | 11,970,313 | +72.72% | 0.052 | 0.040 | 0.055 | 0.055 | 0.055 | 0.199 |
| 10 | 1000 | 22,456,770 | +131.91% | 0.412 | 0.040 | 0.415 | 0.775 | 0.791 | 0.903 |
Documentation
¶
Index ¶
- Constants
- Variables
- func Expand[S ~[]E, E any](s S, n int) S
- func ParseInt64(b []byte) (int64, error)
- func ParseUInt32(b []byte) (uint32, error)
- func Pointer[T any](v T) *T
- func SanitizeSimpleString(buf []byte) []byte
- type Server
- func (s *Server) Close() error
- func (s *Server) CloseWithError(err error) error
- func (s *Server) Next() ([][]byte, error)
- func (s *Server) Reset(rw io.ReadWriter)
- func (s *Server) ResetReader(r io.Reader)
- func (s *Server) SetOptions(opts ServerOptions) error
- func (s *Server) SetRESP2Compat(v bool)
- func (s *Server) Write(v any) error
- func (s *Server) WriteArray(v []any) error
- func (s *Server) WriteArrayBytes(v [][]byte) error
- func (s *Server) WriteArrayHeader(l int) error
- func (s *Server) WriteArrayString(v []string) error
- func (s *Server) WriteAttr(v map[string]any) error
- func (s *Server) WriteAttrBytes(v map[string][]byte) error
- func (s *Server) WriteAttrString(v map[string]string) error
- func (s *Server) WriteBigInt(v big.Int) error
- func (s *Server) WriteBlobError(e error) error
- func (s *Server) WriteBool(v bool) error
- func (s *Server) WriteBytes(v []byte) error
- func (s *Server) WriteError(e error) error
- func (s *Server) WriteExplicitNullArray() error
- func (s *Server) WriteExplicitNullString() error
- func (s *Server) WriteFloat(v float64) error
- func (s *Server) WriteInt(v int) error
- func (s *Server) WriteInt64(v int64) error
- func (s *Server) WriteMap(v map[string]any) error
- func (s *Server) WriteMapBytes(v map[string][]byte) error
- func (s *Server) WriteMapHeader(l int) error
- func (s *Server) WriteMapString(v map[string]string) error
- func (s *Server) WriteNullArray() error
- func (s *Server) WriteNullString() error
- func (s *Server) WriteOK() error
- func (s *Server) WritePush(v []any) error
- func (s *Server) WritePushBytes(v [][]byte) error
- func (s *Server) WritePushString(v []string) error
- func (s *Server) WriteSet(v []any) error
- func (s *Server) WriteSetBytes(v [][]byte) error
- func (s *Server) WriteSetHeader(l int) error
- func (s *Server) WriteSetString(v []string) error
- func (s *Server) WriteStatusBytes(v []byte) error
- func (s *Server) WriteStatusString(v string) error
- func (s *Server) WriteString(v string) error
- func (s *Server) WriteVerbatimBytes(v []byte) error
- func (s *Server) WriteVerbatimString(v string) error
- type ServerOptions
Constants ¶
const ( MaxInlineSize = 64 * 1024 // 64 KiB MaxMultiBulkLength = math.MaxInt32 MaxBulkLength = 128 * 1024 * 1024 // 128 MiB )
const ReaderBufferSize = 65536
const WriterBufferSize = 65536
Variables ¶
var ( ErrProtoUnbalancedQuotes = errors.New("Protocol error: unbalanced quotes in request") ErrProtoInvalidMultiBulkLength = errors.New("Protocol error: invalid multibulk length") ErrProtoInvalidBulkLength = errors.New("Protocol error: invalid bulk length") ErrProtoExpectedString = errors.New("Protocol error: expected '$'") )
Functions ¶
func Expand ¶
Expand works similarly to slices.Grow but returns the expanded slice rather than the capped slice.
func ParseInt64 ¶
func ParseUInt32 ¶
func SanitizeSimpleString ¶
SanitizeSimpleString replaces all '\r' and '\n' characters with spaces. Useful when writing untrusted error messages to the client.
Types ¶
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
func NewServer ¶
func NewServer(rw io.ReadWriter) *Server
NewServer returns a new wrapped incoming connection with sane default parameters set.
func (*Server) Close ¶
Close gracefully closes the incoming connection after flushing any pending writes.
func (*Server) CloseWithError ¶
CloseWithError closes the incoming connection after writing an error response. This is a convenience function that combines WriteError and Close.
func (*Server) Next ¶
Next reads the next command from the incoming connection and returns it as a slice of byte slices. The returned slice is only valid until the next call to Next as it is reused for each command. If in doubt, copy the slice and every byte slice it contains to a newly allocated slice and byte slices.
func (*Server) Reset ¶
func (s *Server) Reset(rw io.ReadWriter)
Reset starts reading and writing commands from the newly passed reader and writer. Mostly used for testing purposes.
func (*Server) ResetReader ¶
ResetReader starts reading commands from the newly passed reader. Mostly used for testing purposes.
func (*Server) SetOptions ¶
func (s *Server) SetOptions(opts ServerOptions) error
SetOptions sets the options for the incoming connection.
func (*Server) SetRESP2Compat ¶
SetRESP2Compat sets the RESP2 compatibility mode of the incoming connection. This mode is useful when talking with a RESP2 client that does not support the new RESP3 types. In this mode, Write functions will convert RESP3 types to RESP2 types where possible.
func (*Server) WriteArray ¶
WriteArray writes an array of any values that can be converted to a RESP type.
func (*Server) WriteArrayBytes ¶
WriteArrayBytes is a convenience method to write an array of Bulk strings.
func (*Server) WriteArrayHeader ¶
WriteArrayHeader writes an [Array](https://redis.io/docs/latest/develop/reference/protocol-spec/#array-reply) header.
func (*Server) WriteArrayString ¶
WriteArrayString is a convenience method to write an array of Bulk strings.
func (*Server) WriteAttr ¶
WriteAttr writes an [Attribute](https://github.com/antirez/RESP3/blob/master/spec.md#attribute-type) with the given data. For RESP2 connections, function calls are silently discarded and no data is written
func (*Server) WriteAttrBytes ¶
WriteAttrBytes writes an [Attribute](https://github.com/antirez/RESP3/blob/master/spec.md#attribute-type) with the given data. For RESP2 connections, function calls are silently discarded and no data is written
func (*Server) WriteAttrString ¶
WriteAttrString writes an [Attribute](https://github.com/antirez/RESP3/blob/master/spec.md#attribute-type) with the given data. For RESP2 connections, function calls are silently discarded and no data is written
func (*Server) WriteBigInt ¶
WriteBigInt writes a [Big number](https://redis.io/docs/latest/develop/reference/protocol-spec/#big-number-reply) for RESP3 connections or an [Integer](https://redis.io/docs/latest/develop/reference/protocol-spec/#integer-reply) for RESP2 connections. If v cannot be represented in an int64, the result is undefined when sending to a RESP2 client.
func (*Server) WriteBlobError ¶
WriteBlobError writes a [Bulk error](https://redis.io/docs/latest/develop/reference/protocol-spec/#bulk-error-reply) for RESP3 connections or a sanitized [Simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#error-reply) for RESP2 connections.
func (*Server) WriteBool ¶
WriteBool writes a [Boolean](https://redis.io/docs/latest/develop/reference/protocol-spec/#boolean-reply) for RESP3 connections or an [Integer](https://redis.io/docs/latest/develop/reference/protocol-spec/#integer-reply) of `0` or `1` for RESP2 connections.
func (*Server) WriteBytes ¶
WriteBytes writes a [Bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec/#bulk-string-reply).
func (*Server) WriteError ¶
WriteError writes a sanitized [Simple error](https://redis.io/docs/latest/develop/reference/protocol-spec/#error-reply).
func (*Server) WriteExplicitNullArray ¶
WriteExplicitNullArray writes a [Null Array](https://redis.io/docs/latest/develop/reference/protocol-spec/#nil-array-reply).
func (*Server) WriteExplicitNullString ¶
WriteExplicitNullString writes a [Null Bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec/#nil-reply).
func (*Server) WriteFloat ¶
WriteFloat writes a [Double](https://redis.io/docs/latest/develop/reference/protocol-spec/#double-reply) for RESP3 connections or a [Bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec/#bulk-string-reply) containing the string representation of the float for RESP2 connections.
func (*Server) WriteInt ¶
WriteInt writes an [Integer](https://redis.io/docs/latest/develop/reference/protocol-spec/#integer-reply).
func (*Server) WriteInt64 ¶
WriteInt64 writes an [Integer](https://redis.io/docs/latest/develop/reference/protocol-spec/#integer-reply).
func (*Server) WriteMapBytes ¶
WriteMapBytes is a convenience method to write a map of Bulk strings.
func (*Server) WriteMapHeader ¶
WriteMapHeader writes a [Map](https://redis.io/docs/latest/develop/reference/protocol-spec/#map-reply) header with the specified length. For RESP2 connections, this writes an [Array](https://redis.io/docs/latest/develop/reference/protocol-spec/#array-reply) header with twice the specified length.
func (*Server) WriteMapString ¶
WriteMapString is a convenience method to write a map of Bulk strings.
func (*Server) WriteNullArray ¶
WriteNullArray writes a [Null](https://redis.io/docs/latest/develop/reference/protocol-spec/#null-reply) for RESP3 connections or a [Null Array](https://redis.io/docs/latest/develop/reference/protocol-spec/#nil-array-reply) for RESP2 connections.
func (*Server) WriteNullString ¶
WriteNullString writes a [Null](https://redis.io/docs/latest/develop/reference/protocol-spec/#null-reply) for RESP3 connections or a [Null Bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec/#nil-reply) for RESP2 connections.
func (*Server) WritePush ¶
WritePushHeader writes a [Push](https://redis.io/docs/latest/develop/reference/protocol-spec/#push-event) event with the given data. For RESP2 connections, function calls are silently discarded and no data is written.
func (*Server) WritePushBytes ¶
WritePushHeader writes a [Push](https://redis.io/docs/latest/develop/reference/protocol-spec/#push-event) event with the given data. For RESP2 connections, function calls are silently discarded and no data is written.
func (*Server) WritePushString ¶
WritePushHeader writes a [Push](https://redis.io/docs/latest/develop/reference/protocol-spec/#push-event) event with the given data. For RESP2 connections, function calls are silently discarded and no data is written.
func (*Server) WriteSetBytes ¶
WriteSetBytes is a convenience method to write a set of Bulk strings.
func (*Server) WriteSetHeader ¶
WriteSetHeader writes a [Set](https://redis.io/docs/latest/develop/reference/protocol-spec/#set-reply) header with the specified length. For RESP2 connections, this writes an [Array](https://redis.io/docs/latest/develop/reference/protocol-spec/#array-reply) header with twice the specified length.
func (*Server) WriteSetString ¶
WriteSetString is a convenience method to write a set of Bulk strings.
func (*Server) WriteStatusBytes ¶
WriteSimpleString writes a [Simple string](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-string-reply).
func (*Server) WriteStatusString ¶
WriteSimpleString writes a [Simple string](https://redis.io/docs/latest/develop/reference/protocol-spec/#simple-string-reply).
func (*Server) WriteString ¶
WriteString writes a [Bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec/#bulk-string-reply).
func (*Server) WriteVerbatimBytes ¶
WriteBlobString writes a [Verbatim string](https://redis.io/docs/latest/develop/reference/protocol-spec/#verbatim-string-reply) for RESP3 connections or a [Bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec/#bulk-string-reply) for RESP2 connections. The verbatim string needs to contain the data encoding part and the data itself. Example: `txt:Arbitrary text data`. The data encoding part is stripped when sending the data as Bulk string to RESP2 clients.
func (*Server) WriteVerbatimString ¶
WriteBlobString writes a [Verbatim string](https://redis.io/docs/latest/develop/reference/protocol-spec/#verbatim-string-reply) for RESP3 connections or a [Bulk string](https://redis.io/docs/latest/develop/reference/protocol-spec/#bulk-string-reply) for RESP2 connections. The verbatim string needs to contain the data encoding part and the data itself. Example: `txt:Arbitrary text data`. The data encoding part is stripped when sending the data as Bulk string to RESP2 clients.
type ServerOptions ¶
type ServerOptions struct {
// MaxMultiBulkLength sets the maximum number of elements in a multi-bulk command request.
MaxMultiBulkLength *int
// MaxBulkLength sets the maximum length of a bulk string in bytes.
MaxBulkLength *int
// MaxBufferSize sets the maximum size of the buffer used to read full commands from the client.
MaxBufferSize *int
// RESP2Compat sets the RESP2 compatibility mode of the incoming connection.
// This mode is useful when talking with a RESP2 client that does not support the new RESP3 types.
// In this mode, Write functions will convert RESP3 types to RESP2 types where possible.
RESP2Compat *bool
}
Source Files
Directories