client

Documentation

Index

• Variables
• type ACLUser
• type AuthLogEntry
• type Client
  • func Dial(addr string, timeout time.Duration) (*Client, error)
  • func DialTLS(addr string, certPath, keyPath, caPath string, timeout time.Duration) (*Client, error)
  • func DialTLSWithLogger(addr string, certPath, keyPath, caPath string, timeout time.Duration, ...) (*Client, error)
  • func DialWithLogger(addr string, timeout time.Duration, logger logger.Logger) (*Client, error)
  • func (c *Client) AclDelUser(username string, scratchBuf []byte) error
  • func (c *Client) AclList(scratchBuf []byte) ([]ACLUser, error)
  • func (c *Client) AclLog(scratchBuf []byte) ([]AuthLogEntry, error)
  • func (c *Client) AclSetUser(username, role string, passOptions [][]byte, scratchBuf []byte) error
  • func (c *Client) Auth(password string, scratchBuf []byte) error
  • func (c *Client) AuthUser(username, password string, scratchBuf []byte) error
  • func (c *Client) Close() error
  • func (c *Client) Delete(key []byte, scratchBuf []byte) ([]byte, error)
  • func (c *Client) Get(key []byte, scratchBuf []byte) ([]byte, error)
  • func (c *Client) RoleCreate(role string, rules []string, scratchBuf []byte) error
  • func (c *Client) RoleDelUser(username string, scratchBuf []byte) error
  • func (c *Client) RoleDelete(role string, scratchBuf []byte) error
  • func (c *Client) RoleGetUser(username string, scratchBuf []byte) (RoleUser, error)
  • func (c *Client) RoleList(scratchBuf []byte) ([]RoleListEntry, error)
  • func (c *Client) RoleSetUser(username, role string, passOptions [][]byte, scratchBuf []byte) error
  • func (c *Client) Set(key, value []byte, ttlMs int64, scratchBuf []byte) ([]byte, error)
• type RoleListEntry
• type RoleUser

Variables

var (
	// ErrRequestTooLarge is returned if the generated request exceeds the local stack buffer boundaries.
	ErrRequestTooLarge = network.ErrRequestTooLarge

	// ErrResponseBufferTooSmall is returned if the scratchpad buffer cannot hold the incoming server frame.
	ErrResponseBufferTooSmall = network.ErrResponseBufferTooSmall

	// ErrClientClosed is returned when operating on a closed client.
	ErrClientClosed = errors.New("client: closed")
)

Types

type ACLUser

type ACLUser struct {
	Username   string
	Role       string // empty when the default role applies
	HasPass    bool
	Commands   []string
	Namespaces [][]byte
}

ACLUser is a decoded ACL LIST record.

type AuthLogEntry

type AuthLogEntry struct {
	Timestamp  string // RFC3339, matching the RESP ACL LOG rendering
	Username   string
	RemoteAddr string
	Reason     string
}

AuthLogEntry is one decoded ACL LOG record.

type Client

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

Client is a synchronous connection to a Tellstone server. Client methods must not be called concurrently.

func Dial

func Dial(addr string, timeout time.Duration) (*Client, error)

Dial connects to a Tellstone server pool via the specified TCP address.

func DialTLS

func DialTLS(addr string, certPath, keyPath, caPath string, timeout time.Duration) (*Client, error)

DialTLS connects to a Tellstone server with TLS 1.3 encryption. certPath/keyPath are the client certificate and key for mTLS (pass empty for one-way TLS). caPath is the CA certificate to verify the server (pass empty to skip verification).

func DialTLSWithLogger

func DialTLSWithLogger(addr string, certPath, keyPath, caPath string, timeout time.Duration, logger logger.Logger) (*Client, error)

DialTLSWithLogger connects like DialTLS and reports connection lifecycle events to logger. logger may be nil to disable logging.

func DialWithLogger

func DialWithLogger(addr string, timeout time.Duration, logger logger.Logger) (*Client, error)

DialWithLogger connects like Dial and reports connection lifecycle events to logger. logger may be nil to disable logging.

func (*Client) AclDelUser

func (c *Client) AclDelUser(username string, scratchBuf []byte) error

AclDelUser issues ACL DELUSER <username>.

func (*Client) AclList

func (c *Client) AclList(scratchBuf []byte) ([]ACLUser, error)

AclList issues ACL LIST and returns the decoded users.

func (*Client) AclLog

func (c *Client) AclLog(scratchBuf []byte) ([]AuthLogEntry, error)

AclLog issues ACL LOG and returns the recent auth-failure buffer in chronological order.

func (*Client) AclSetUser

func (c *Client) AclSetUser(username, role string, passOptions [][]byte, scratchBuf []byte) error

AclSetUser issues ACL SETUSER <username> <role> [>password] [nopass] on the binary protocol. The role must already exist. At least one password option is required: pass []byte("nopass") for a passwordless user. A ">password" option transmits the password in cleartext unless the connection was made with DialTLS — use DialTLS when passing secrets.

func (*Client) Auth

func (c *Client) Auth(password string, scratchBuf []byte) error

Auth authenticates the client with a password (single-password mode). Must be called after Dial/DialTLS when the server has --require-pass set. scratchBuf must be large enough to hold the server response.

func (*Client) AuthUser

func (c *Client) AuthUser(username, password string, scratchBuf []byte) error

AuthUser authenticates with a username/password pair (RBAC mode). Must be called after Dial/DialTLS when the server runs with --rbac-config. The password travels in cleartext unless the connection was made with DialTLS — use DialTLS when transmitting secrets.

func (*Client) Close

func (c *Client) Close() error

Close closes the underlying network connection. Calling Close on a nil client returns nil.

func (*Client) Delete

func (c *Client) Delete(key []byte, scratchBuf []byte) ([]byte, error)

Delete removes a key-value entity permanently from the remote cluster space.

func (*Client) Get

func (c *Client) Get(key []byte, scratchBuf []byte) ([]byte, error)

Get retrieves a binary value from the remote engine using its key identifier.

func (*Client) RoleCreate

func (c *Client) RoleCreate(role string, rules []string, scratchBuf []byte) error

RoleCreate issues ROLE CREATE <name> <rule>... on the binary protocol. Rule tokens follow the RESP conventions: "+cmd", "-cmd", "+@category", "-@category", "~prefix", "~*". Fails when the role already exists.

func (*Client) RoleDelUser

func (c *Client) RoleDelUser(username string, scratchBuf []byte) error

RoleDelUser issues ROLE DELUSER <username>.

func (*Client) RoleDelete

func (c *Client) RoleDelete(role string, scratchBuf []byte) error

RoleDelete issues ROLE DELETE <role>.

func (*Client) RoleGetUser

func (c *Client) RoleGetUser(username string, scratchBuf []byte) (RoleUser, error)

RoleGetUser issues ROLE GETUSER <username> and returns the decoded record.

func (*Client) RoleList

func (c *Client) RoleList(scratchBuf []byte) ([]RoleListEntry, error)

RoleList issues ROLE LIST and returns the decoded roles.

func (*Client) RoleSetUser

func (c *Client) RoleSetUser(username, role string, passOptions [][]byte, scratchBuf []byte) error

RoleSetUser issues ROLE SETUSER <username> <role> [>password] [nopass]. At least one password option is required: pass []byte("nopass") for a passwordless user. The last password option wins; nopass clears the hash. A ">password" option transmits the password in cleartext unless the connection was made with DialTLS — use DialTLS when passing secrets.

func (*Client) Set

func (c *Client) Set(key, value []byte, ttlMs int64, scratchBuf []byte) ([]byte, error)

Set stores a binary key-value pair with a millisecond-based TTL inside the remote engine.

type RoleListEntry

type RoleListEntry struct {
	Name       string
	Commands   []string
	Namespaces [][]byte
}

RoleListEntry is one role from a ROLE LIST response.

type RoleUser

type RoleUser struct {
	Role    string // empty when the user has no explicit role
	HasPass bool
}

RoleUser is a decoded ROLE GETUSER record.