connections

package
v0.311.0 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package connections is a branch-connections HTTP client that follows the patterns of github.com/planetscale/planetscale-go: a typed Client over shared auth, base-URL, and transport machinery. The auth header construction, error formatting, and response decode helpers mirror the equivalents in planetscale-go.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BlockingCounts 

func BlockingCounts(connections []Connection) map[int]int

BlockingCounts returns each connection's downstream blocking depth by PID.

func DerefString 

func DerefString(value *string) string

DerefString returns the pointed-to string, or "" when nil.

func JoinInts 

func JoinInts(values []int) string

JoinInts renders a blocked-by PID slice as a comma-separated string.

func JoinWaitEvents 

func JoinWaitEvents(waitEventType, waitEvent string) string

JoinWaitEvents renders the wait-event type/event pair as "type/event", collapsing to whichever side is present when one is empty.

func SanitizeDisplayText added in v0.306.0 

func SanitizeDisplayText(value string) string

SanitizeDisplayText strips ASCII C0 controls, DEL, and C1 controls from text that will be written to a terminal. Connection observability fields such as query text, application_name, username, and client_addr can contain attacker-controlled escape sequences (CSI/OSC) from anyone with connect access to the observed branch.

func SanitizeMultilineDisplayText added in v0.306.0 

func SanitizeMultilineDisplayText(value string) string

SanitizeMultilineDisplayText sanitizes each line of value while preserving newline separators so multi-line query text stays readable in human output.

func SortConnections 

func SortConnections(connections []Connection, mode SortMode)

func UserFacingError 

func UserFacingError(err error, action string) error

func UserFacingErrorText 

func UserFacingErrorText(err error, action string) string

Types

type ActionResult 

type ActionResult struct {
	Success  bool   `json:"success"`
	Keyspace string `json:"keyspace,omitempty"`
	Shard    string `json:"shard,omitempty"`
	Tablet   string `json:"tablet,omitempty"`
	ID       int64  `json:"id,omitempty"`
	Kind     string `json:"kind,omitempty"`
}

type ActionTarget 

type ActionTarget struct {
	Instance      string
	PID           int
	ConnectionID  *string
	TransactionID *string
	QueryID       *string
}

ActionTarget identifies the connection an action acts on. Instance and PID describe the selected row; ConnectionID, TransactionID, and QueryID are the server-issued IDs for connection, transaction, and query verification.

type AvailableTargets 

type AvailableTargets struct {
	Keyspaces []string `json:"keyspaces,omitempty"`
	Shards    []string `json:"shards,omitempty"`
}

type Client 

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

func NewClient 

func NewClient(cfg ClientConfig) (*Client, error)

func (*Client) CancelQuery 

func (s *Client) CancelQuery(ctx context.Context, target ActionTarget) error

CancelQuery asks the backend to cancel the active query identified by target.QueryID.

func (*Client) CancelQueryResult 

func (s *Client) CancelQueryResult(ctx context.Context, target ActionTarget) (ActionResult, error)

func (*Client) List 

func (s *Client) List(ctx context.Context, sort SortMode) (ConnectionList, error)

func (*Client) TerminateConnection 

func (s *Client) TerminateConnection(ctx context.Context, target ActionTarget) error

TerminateConnection force-terminates the connection identified by target.ConnectionID without regard to its current query or transaction. Operator-initiated; gated by a y/n confirmation in the TUI.

func (*Client) TerminateConnectionResult 

func (s *Client) TerminateConnectionResult(ctx context.Context, target ActionTarget) (ActionResult, error)

func (*Client) TerminateTransaction 

func (s *Client) TerminateTransaction(ctx context.Context, target ActionTarget) error

TerminateTransaction asks the backend to terminate the connection only if its current transaction matches target.TransactionID — i.e., reject if the connection has moved on. Same-transaction semantics live on the server.

func (*Client) TerminateTransactionResult 

func (s *Client) TerminateTransactionResult(ctx context.Context, target ActionTarget) (ActionResult, error)

TerminateTransactionResult asks the backend to terminate a transaction and returns any action metadata the backend provides.

type ClientConfig 

type ClientConfig struct {
	BaseURL        string
	Organization   string
	Database       string
	Branch         string
	Keyspace       string
	Shard          string
	AccessToken    string
	ServiceTokenID string
	ServiceToken   string
	HTTPClient     *http.Client
	RequestTimeout time.Duration
}

type Connection 

type Connection struct {
	PID             int           `json:"pid"`
	Instance        string        `json:"instance"`
	InstanceRole    string        `json:"instance_role,omitempty"`
	Username        string        `json:"username"`
	ApplicationName string        `json:"application_name"`
	DatabaseName    string        `json:"database,omitempty"`
	ClientAddr      string        `json:"client_addr"`
	State           string        `json:"state"`
	WaitEventType   string        `json:"wait_event_type"`
	WaitEvent       string        `json:"wait_event"`
	BackendType     string        `json:"backend_type"`
	XactStart       *time.Time    `json:"xact_start,omitempty"`
	QueryStart      *time.Time    `json:"query_start,omitempty"`
	ConnectionID    *string       `json:"connection_id,omitempty"`
	TransactionID   *string       `json:"transaction_id,omitempty"`
	QueryID         *string       `json:"query_id,omitempty"`
	Duration        time.Duration `json:"duration"`
	BlockedBy       []int         `json:"blocked_by,omitempty"`
	QueryText       string        `json:"query_text,omitempty"`
}

func (Connection) HumanFields 

func (c Connection) HumanFields() [][2]string

HumanFields returns the connection's scalar fields as ordered (name, value) pairs for vertical, MySQL `\G`-style rendering. The query text is excluded — callers render it separately because it is multi-line. This is the single source of truth shared by the agent-cli `list --format human` output and the interactive detail view, so the two never drift.

type ConnectionList 

type ConnectionList struct {
	CapturedAt   time.Time      `json:"captured_at"`
	DatabaseKind DatabaseKind   `json:"database_kind,omitempty"`
	Connections  []Connection   `json:"connections"`
	Sort         SortMode       `json:"sort"`
	Instances    []InstanceMeta `json:"instances,omitempty"`
	Topology     *Topology      `json:"topology,omitempty"`
}

func NewConnectionList 

func NewConnectionList(capturedAt time.Time, connections []Connection, sort SortMode) ConnectionList

func (ConnectionList) HasUnreachableInstance added in v0.291.0 

func (l ConnectionList) HasUnreachableInstance() bool

HasUnreachableInstance reports whether the server flagged any instance as unreachable in the list response. These partial fan-out failures drive the "N of M instances unreachable" banner.

type DatabaseKind 

type DatabaseKind string
const (
	DatabaseKindMySQL      DatabaseKind = "mysql"
	DatabaseKindPostgreSQL DatabaseKind = "postgresql"
)

type HTTPError 

type HTTPError struct {
	Op         string
	StatusCode int
	Message    string
	Available  AvailableTargets
}

func (*HTTPError) Error 

func (e *HTTPError) Error() string

type InstanceMeta 

type InstanceMeta struct {
	ID    string `json:"id"`
	Role  string `json:"role"`
	Error string `json:"error,omitempty"`
}

type SortMode 

type SortMode string
const (
	SortByTransactionStart SortMode = "xact_start"
	SortByDuration         SortMode = "duration"
	SortByBlocked          SortMode = "blocked"
)

type Topology 

type Topology struct {
	Keyspace string `json:"keyspace,omitempty"`
	Shard    string `json:"shard,omitempty"`
	Tablet   string `json:"tablet,omitempty"`
}

type UnknownInstanceError 

type UnknownInstanceError struct {
	Instance string
	Valid    []string
}

UnknownInstanceError reports an --instance filter value that matches none of the instances in the list response.

func (*UnknownInstanceError) Error 

func (e *UnknownInstanceError) Error() string

Source Files

View all Source files

Directories

Path Synopsis

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.