connect

Documentation

Index

• Variables
• type Client
  • func NewClient(baseUrl *url.URL, token string, opts Options) (*Client, error)
  • func (c *Client) Call(ctx context.Context, req Request) (Message, error)
  • func (c *Client) Close() error
  • func (c *Client) Connect(ctx context.Context) error
  • func (c *Client) Done() <-chan struct{}
  • func (c *Client) Dropped() uint64
  • func (c *Client) Send(req Request) error
  • func (c *Client) Subscribe(sub Subscription, handler Handler) error
• type Handler
• type Message
• type MessageError
  • func (e *MessageError) Error() string
• type Options
  • func DefaultOptions() Options
• type Request
• type Subscription

Variables

var (
	// ErrAuthFailed reports a token Home Assistant refused. It is terminal:
	// retrying a rejected token only produces the same answer more slowly.
	ErrAuthFailed = errors.New("authentication failed")

	// ErrNotConnected reports a send attempted while no connection was live.
	ErrNotConnected = errors.New("not connected")

	// ErrUnexpectedFrame reports a non-text websocket frame, which the Home
	// Assistant protocol never sends.
	ErrUnexpectedFrame = errors.New("unexpected websocket frame type")

	// ErrClosed reports use of a client whose context has already been cancelled.
	ErrClosed = errors.New("client closed")

	// ErrCallFailed reports a request Home Assistant answered with success=false.
	ErrCallFailed = errors.New("call failed")
)

Types

type Client

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

Client owns a single Home Assistant websocket connection, re-establishing it as needed and replaying subscriptions each time it does.

func NewClient

func NewClient(baseUrl *url.URL, token string, opts Options) (*Client, error)

NewClient prepares a client for the Home Assistant instance at baseUrl. No connection is made until Connect is called.

func (*Client) Call

func (c *Client) Call(ctx context.Context, req Request) (Message, error)

Call writes a request and waits for Home Assistant to answer it.

func (*Client) Close

func (c *Client) Close() error

Close shuts the client down and waits for its goroutines to finish.

func (*Client) Connect

func (c *Client) Connect(ctx context.Context) error

Connect establishes the first connection and starts the goroutines that keep it alive. It fails fast, so an unreachable host or a refused token surfaces to the caller rather than disappearing into a retry loop.

func (*Client) Done

func (c *Client) Done() <-chan struct{}

Done is closed once the client has stopped for good, whether because it was closed or because reconnection was abandoned.

Callers need this to notice the second case. Giving up cancels a context derived from the caller's, which does not propagate upwards, so an app waiting only on its own context would sit there indefinitely holding a client that will never deliver another event.

func (*Client) Dropped

func (c *Client) Dropped() uint64

Dropped reports how many events have been discarded because the queue was full. It is non-zero only when handlers cannot keep up with the event rate.

func (*Client) Send

func (c *Client) Send(req Request) error

Send writes a request and returns as soon as it is on the wire. The result Home Assistant sends back is still correlated, but only to log a failure: without it a call_service against a missing entity fails in total silence.

func (*Client) Subscribe

func (c *Client) Subscribe(sub Subscription, handler Handler) error

Subscribe registers interest in an event stream. The subscription is retained and re-established on every subsequent connection.

type Handler

type Handler func(Message)

Handler receives each message delivered for a subscription. It runs on a worker goroutine, so it may block without stalling the reader.

type Message

type Message struct {
	ID      int64
	Type    string
	Success bool
	Raw     []byte
	Error   *MessageError
}

Message is a decoded frame from Home Assistant. Raw is retained because callers decode their own event payloads out of it.

type MessageError

type MessageError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

MessageError is the error object Home Assistant attaches to a failed result.

func (*MessageError) Error

func (e *MessageError) Error() string

type Options

type Options struct {
	// QueueSize bounds the event backlog held between the reader and the
	// workers. Home Assistant disconnects a client that stops draining its
	// socket for five seconds, so this queue is deliberately finite: shedding
	// load is survivable, being disconnected is not.
	QueueSize int

	// Workers is the number of goroutines draining the queue. Handlers run on
	// these, so a slow handler costs a worker rather than the connection.
	Workers int

	// PingInterval is how often liveness is checked once the connection is idle.
	PingInterval time.Duration

	// PingTimeout bounds how long a ping waits before the connection is
	// considered dead and torn down.
	PingTimeout time.Duration

	// DialTimeout bounds a single connection attempt, including the auth
	// handshake.
	DialTimeout time.Duration

	// WriteTimeout bounds a single outgoing message.
	WriteTimeout time.Duration

	// HealthyAfter is how long a connection must survive before the backoff
	// sequence resets. Without it a connection that dies immediately after each
	// handshake would retry at the base delay forever.
	HealthyAfter time.Duration
}

Options tunes the connection layer. The zero value is not usable; start from DefaultOptions and adjust.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the settings used when none are supplied.

type Request

type Request interface {
	SetID(id int64)
}

Request is a message the client stamps with a connection-scoped id before sending. Ids are allocated per client rather than per process, so two Apps in one binary no longer share a counter.

type Subscription

type Subscription struct {
	// EventType names the event to receive. An empty value subscribes to every
	// event Home Assistant emits.
	EventType string
}

Subscription declares an interest in a stream of Home Assistant events.

It is data rather than an action so the client can replay it. Subscribing imperatively at registration time means a reconnect silently loses every listener: Home Assistant replays nothing, and the ids handed out by the old connection are meaningless on the new one.