protocol

Documentation

Overview

Package protocol implements the KDE Connect v8 packet framing. This package has zero external imports — stdlib only.

Index

• Constants
• func PoolStats() (acquires, misses int64)
• func ReleasePacket(p *Packet)
• func SanitizeDeviceName(name string) string
• func WritePacket(w io.Writer, p *Packet) error
• type IdentityBody
• type Packet
  • func AcquirePacket() *Packet
  • func NewIdentityPacket(deviceID, deviceName, deviceType string, tcpPort int, ...) (*Packet, error)
  • func NewPacket(typ string, body interface{}) (*Packet, error)
  • func NewPairPacket(pair bool) (*Packet, error)
  • func ReadPacket(r *bufio.Reader) (*Packet, error)
  • func (p *Packet) Reset()
• type PairBody
• type TransferInfo

Constants

const (
	PairAccept = true
	PairReject = false
)

Pairing direction constants.

const MaxDeviceNameLength = 32

const MaxPacketSize = 4 * 1024 * 1024

MaxPacketSize is the maximum allowed line length for a single packet (4 MB). Lines exceeding this are rejected to prevent memory exhaustion.

const ProtocolVersion = 8

ProtocolVersion is the KDE Connect protocol version we advertise. KDE Connect uses version 8 which requires post-TLS identity exchange.

const TypeIdentity = "kdeconnect.identity"

TypeIdentity is the packet type for identity exchange.

const TypePair = "kdeconnect.pair"

TypePair is the packet type for pairing requests/responses.

Functions

func PoolStats

func PoolStats() (acquires, misses int64)

PoolStats returns packet pool usage counters for diagnostic logging. hits = acquires - misses. A miss rate above ~20% under steady load may indicate pool pressure from GC eviction.

func ReleasePacket

func ReleasePacket(p *Packet)

ReleasePacket returns a Packet to the pool after zeroing it.

func SanitizeDeviceName

func SanitizeDeviceName(name string) string

SanitizeDeviceName strips potential terminal injection and XSS characters and truncates the name to a maximum length per the KDE Connect specification.

func WritePacket

func WritePacket(w io.Writer, p *Packet) error

WritePacket serializes a Packet as a single line of JSON followed by \n.

Types

type IdentityBody

type IdentityBody struct {
	DeviceID              string   `json:"deviceId"`
	DeviceName            string   `json:"deviceName"`
	DeviceType            string   `json:"deviceType"`
	ProtocolVersion       int      `json:"protocolVersion"`
	TCPPort               int      `json:"tcpPort"`
	IncomingCapabilities  []string `json:"incomingCapabilities,omitempty"`
	OutgoingCapabilities  []string `json:"outgoingCapabilities,omitempty"`
	TargetDeviceID        string   `json:"targetDeviceId,omitempty"`
	TargetProtocolVersion int      `json:"targetProtocolVersion,omitempty"`
}

IdentityBody contains the fields of an identity packet body.

type Packet

type Packet struct {
	ID                  int64           `json:"id"`
	Type                string          `json:"type"`
	Body                json.RawMessage `json:"body"`
	PayloadSize         int64           `json:"payloadSize,omitempty"`
	PayloadTransferInfo *TransferInfo   `json:"payloadTransferInfo,omitempty"`
}

Packet represents a single KDE Connect packet on the wire. Body is kept as json.RawMessage so the router never unmarshals plugin payloads.

func AcquirePacket

func AcquirePacket() *Packet

AcquirePacket returns a zeroed Packet from the pool.

func NewIdentityPacket

func NewIdentityPacket(
	deviceID, deviceName, deviceType string,
	tcpPort int,
	incoming, outgoing []string,
) (*Packet, error)

NewIdentityPacket creates a fully-formed identity packet ready for the wire.

func NewPacket

func NewPacket(typ string, body interface{}) (*Packet, error)

NewPacket creates a new Packet with the current timestamp and given type/body.

func NewPairPacket

func NewPairPacket(pair bool) (*Packet, error)

NewPairPacket creates a pairing packet (accept or reject).

func ReadPacket

func ReadPacket(r *bufio.Reader) (*Packet, error)

ReadPacket reads a single newline-delimited JSON packet from r. The returned Packet is from the pool — call ReleasePacket when done.

func (*Packet) Reset

func (p *Packet) Reset()

Reset zeroes all fields so a pooled Packet can be safely reused.

type PairBody

type PairBody struct {
	Pair      bool  `json:"pair"`
	Timestamp int64 `json:"timestamp,omitempty"`
}

PairBody contains the fields of a pair packet body.

type TransferInfo

type TransferInfo struct {
	Port int `json:"port"`
}

TransferInfo holds the port for side-channel file transfers.