device

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Oct 23, 2026 License: AGPL-3.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EventSourceHeartbeat     = httpapi.Heartbeat
	EventSourceWebUI         = httpapi.WebUi
	EventSourceExpiry        = httpapi.Expiry
	EventSourceLimitExceeded = httpapi.LimitExceeded
)
View Source 
const (
	EventTriggerUser          = httpapi.AddressEventTriggerUser
	EventTriggerSchedule      = httpapi.AddressEventTriggerSchedule
	EventTriggerNetworkChange = httpapi.AddressEventTriggerNetworkChange
	EventTriggerSystem        = httpapi.AddressEventTriggerSystem
)
View Source 
const (
	AttrKeyError            = logging.AttrKeyError
	AttrKeyAddressID        = "address_id"
	AttrKeyAddressIP        = "address_ip"
	AttrKeyClientIP         = "client_ip"
	AttrKeyCount            = "count"
	AttrKeyDeviceID         = "device_id"
	AttrKeyDeviceName       = "device_name"
	AttrKeyOwnerID          = "owner_id"
	AttrKeyAddressEventType = "address_event_type"
	AttrKeyTriggerType      = "trigger_type"
)

Slog attribute key names for the device domain. Use these constants when logging so keys are consistent and typo-safe across handlers and services.

View Source 
const APIKeyPrefix = "wdk_"

Variables

View Source 
var (
	ErrDeviceNotFound          = errors.New("device not found")
	ErrDeviceDisabled          = errors.New("device is disabled")
	ErrOwnerNotFound           = errors.New("device owner not found")
	ErrNoAPIKey                = errors.New("device has no API key")
	ErrDuplicateDeviceName     = errors.New("device name already in use")
	ErrAddressNotFound         = errors.New("device address not found")
	ErrInvalidIPFormat         = errors.New("invalid IP address format")
	ErrInvalidDeviceIP         = errors.New("ip address is not valid for device registration")
	ErrTrustedProxyIPRejected  = errors.New("ip address belongs to trusted proxy")
	ErrAddressNotOwnedByDevice = errors.New("address is not owned by the device")
	ErrInvalidAPIKey           = errors.New("invalid api key")
	ErrInvalidDeviceName       = errors.New("device name must be between 1 and 50 characters")
	ErrDescriptionTooLong      = errors.New("description must be 200 characters or fewer")
	ErrIconTooLong             = errors.New("icon must be 80 characters or fewer")
)

Functions

func AddressEventKindToAPI added in v0.6.0 

func AddressEventKindToAPI(k AddressEventKind) httpapi.AddressEventKind

AddressEventKindToAPI converts the domain event kind to its API representation. The exhaustive linter fails this switch when a new AddressEventKind value is added without a corresponding case here.

func GenerateAPIKey added in v0.3.0 

func GenerateAPIKey() (rawKey string, keyHash string, keyPrefix string, error error)

GenerateAPIKey generates a new API key and returns the raw key (to send to user), the key hash (to store in DB), and the key prefix (for display).

func HashAPIKey added in v0.3.0 

func HashAPIKey(rawKey string) string

HashAPIKey hashes the API key using SHA-256 and returns base64url encoded hash. This mirrors the pattern used in auth.hashRawToken.

func ParseAndValidateIP added in v0.3.0 

func ParseAndValidateIP(ipInput string) (netip.Addr, error)

ParseAndValidateIP parses and validates that the given string is a valid IPv4 or IPv6 address. It ignores the port if present and only cares about the IP component. The result is always canonical: an IPv4-mapped IPv6 address (::ffff:a.b.c.d) is unmapped to its plain IPv4 form so stored addresses never depend on representation. TODO: Make private once the address_test go through the NewCreateAddressParams

func PrincipalDeviceContextMiddleware 

func PrincipalDeviceContextMiddleware(apiKeyAuthenticator APIKeyAuthenticator) func(http.Handler) http.Handler

PrincipalDeviceContextMiddleware resolves the api key into a Device Principal and injects it into the context.

func TTLRiskToAPI added in v0.6.0 

func TTLRiskToAPI(r TTLRisk) httpapi.TTLRisk

TTLRiskToAPI converts the domain TTL risk to its API representation. The exhaustive linter fails this switch when a new TTLRisk value is added without a corresponding case here.

func WithPrincipal 

func WithPrincipal(ctx context.Context, principal Principal) context.Context

Types

type APIKeyAuthenticator 

type APIKeyAuthenticator interface {
	Authenticate(ctx context.Context, rawKey string) (*Principal, error)
}

APIKeyAuthenticator defines the interface for authenticating device API keys.

type Address 

type Address struct {
	ID        ids.AddressID `db:"id"`
	DeviceID  ids.DeviceID  `db:"device_id"`
	IP        string        `db:"ip"`
	IsEnabled bool          `db:"is_enabled"`
	Source    EventSource   `db:"source"`
	CreatedAt time.Time     `db:"created_at"`
	UpdatedAt time.Time     `db:"updated_at"`
}

Address represents an address row with its current enabled/disabled state and metadata.

type AddressEvent 

type AddressEvent struct {
	Type       AddressEventType
	AddressID  ids.AddressID
	DeviceID   ids.DeviceID
	OccurredAt time.Time
}

func NewAddressEvent 

func NewAddressEvent(address *Address, eventType AddressEventType) AddressEvent

func (AddressEvent) IsAddressEnabled 

func (e AddressEvent) IsAddressEnabled() bool

IsAddressEnabled returns true for Created, Enabled, and Refreshed events (address is enabled); false for Disabled.

func (AddressEvent) LogValue 

func (e AddressEvent) LogValue() slog.Value

type AddressEventKind added in v0.6.0 

type AddressEventKind string

AddressEventKind classifies an address event against the immediately preceding event for the same address, independent of any time window. 

const (
	AddressEventKindCreated  AddressEventKind = "created"
	AddressEventKindEnabled  AddressEventKind = "enabled"
	AddressEventKindDisabled AddressEventKind = "disabled"
	AddressEventKindRefresh  AddressEventKind = "refresh"
)

type AddressEventType added in v0.6.0 

type AddressEventType string
const (
	EventTypeAddressCreated   AddressEventType = "address_created"
	EventTypeAddressEnabled   AddressEventType = "address_enabled"
	EventTypeAddressRefreshed AddressEventType = "address_refreshed"
	EventTypeAddressDisabled  AddressEventType = "address_disabled"
)

type AddressHistoryEventRow added in v0.6.0 

type AddressHistoryEventRow struct {
	ID                int64            `db:"id"`
	CreatedAt         time.Time        `db:"created_at"`
	IP                string           `db:"ip"`
	IsEnabled         bool             `db:"is_enabled"`
	Source            EventSource      `db:"source"`
	TriggerType       EventTrigger     `db:"trigger_type"`
	DeviceID          ids.DeviceID     `db:"device_id"`
	DeviceName        string           `db:"device_name"`
	RenewalGapSeconds *int64           `db:"renewal_gap_seconds"`
	EventKind         AddressEventKind `db:"event_kind"`
	TTLRisk           TTLRisk          `db:"ttl_risk"`
	TTLSeconds        *int64           `db:"ttl_seconds"`
}

AddressHistoryEventRow is one enriched address event.

type AddressHistoryEvents added in v0.6.0 

type AddressHistoryEvents struct {
	Events []AddressHistoryEventRow
	Total  int
}

AddressHistoryEvents is a page of enriched events plus the total matching the filters (ignoring the cursor), for pagination.

type AddressHistoryQuery 

type AddressHistoryQuery struct {
	From     time.Time
	To       time.Time
	Filters  []filterx.Filter
	BeforeID *int64
	Limit    int
}

AddressHistoryQuery is the validated, normalized form of an address-history request — shared by the events and histogram endpoints. BeforeID and Limit are only meaningful for the events page.

func NewAddressHistoryHistogramQuery added in v0.6.0 

func NewAddressHistoryHistogramQuery(params httpapi.GetAddressHistoryHistogramParams) (AddressHistoryQuery, error)

NewAddressHistoryHistogramQuery validates and normalizes GET /address-history/histogram params.

func NewAddressHistoryQuery added in v0.6.0 

func NewAddressHistoryQuery(params httpapi.GetAddressHistoryParams) (AddressHistoryQuery, error)

NewAddressHistoryQuery validates and normalizes GET /address-history params.

type AddressHistoryTuningQuery added in v0.7.0 

type AddressHistoryTuningQuery struct {
	From     time.Time
	To       time.Time
	DeviceID *ids.DeviceID
}

AddressHistoryTuningQuery is the validated window behind GET /address-history/tuning. Unlike AddressHistoryQuery it carries no filterx filters — the endpoint is window-scoped by contract, so there is nothing here for a filter to narrow.

func NewAddressHistoryTuningQuery added in v0.7.0 

func NewAddressHistoryTuningQuery(params httpapi.GetAddressHistoryTuningParams) AddressHistoryTuningQuery

NewAddressHistoryTuningQuery normalizes GET /address-history/tuning params, defaulting to the same window as the other address-history endpoints.

type AddressObserver 

type AddressObserver interface {
	OnAddressEvent(ctx context.Context, event AddressEvent)
}

type AddressView added in v0.6.0 

type AddressView struct {
	ID        ids.AddressID `db:"id"`
	DeviceID  ids.DeviceID  `db:"device_id"`
	IP        string        `db:"ip"`
	IsEnabled bool          `db:"is_enabled"`
	Source    string        `db:"source"`
	UpdatedAt time.Time     `db:"updated_at"`
	CreatedAt time.Time     `db:"created_at"`
	ExpiresAt *time.Time    `db:"expires_at"`
}

type CreateAddressParams 

type CreateAddressParams struct {
	DeviceID ids.DeviceID
	IP       netip.Addr
}

CreateAddressParams holds only what is necessary to create an address.

func NewCreateAddressParams 

func NewCreateAddressParams(deviceID ids.DeviceID, ipAddress string, trustedProxy netip.Addr) (CreateAddressParams, error)

type CreateDeviceInput added in v0.4.0 

type CreateDeviceInput struct {
	Name           string
	OwnerID        *ids.UserID // nil = owned by the calling principal
	Description    *string
	Icon           *string
	GenerateAPIKey bool // mint an API key in the same transaction, returned once
}

CreateDeviceInput carries the full set of create-time choices. Profile fields and the credential are optional — a device is valid with only a name and owner, so the bare CreateDevice below is just this with everything else zero.

type CreateDeviceParams 

type CreateDeviceParams struct {
	Name        string
	OwnerID     ids.UserID
	Description *string
	Icon        *string
}

type Device 

type Device struct {
	ID          ids.DeviceID `db:"id"`
	Name        string       `db:"name"`
	Description *string      `db:"description"`
	Icon        *string      `db:"icon"`
	CreatedAt   time.Time    `db:"created_at"`
	UpdatedAt   time.Time    `db:"updated_at"`
	DeletedAt   *time.Time   `db:"deleted_at"`
	DisabledAt  *time.Time   `db:"disabled_at"`
	KeyPrefix   *string      `db:"key_prefix"`
	OwnerID     ids.UserID   `db:"owner_id"`
}

func (*Device) Update added in v0.2.0 

func (d *Device) Update(name *string, description **string, icon **string, ownerID *ids.UserID) error

Update applies patch inputs to the device in-place, validating each field. Fields with a nil pointer are left unchanged. The device is not mutated unless all validations pass.

  • name: nil = keep current; non-nil = rename (validated)
  • description: nil = keep current; non-nil ptr to nil = clear; non-nil ptr to value = set
  • icon: same semantics as description

type DeviceEvent added in v0.6.0 

type DeviceEvent struct {
	Type       DeviceEventType
	DeviceID   ids.DeviceID
	OccurredAt time.Time
}

DeviceEvent signals a device-level change.

func NewDeviceEvent added in v0.3.0 

func NewDeviceEvent(deviceID ids.DeviceID, eventType DeviceEventType) DeviceEvent

func (DeviceEvent) LogValue added in v0.6.0 

func (e DeviceEvent) LogValue() slog.Value

type DeviceEventType added in v0.6.0 

type DeviceEventType string
const (
	DeviceEventTypeOwnershipChanged DeviceEventType = "device_ownership_changed"
)

type DeviceObserver added in v0.6.0 

type DeviceObserver interface {
	OnDeviceEvent(ctx context.Context, event DeviceEvent)
}

type EventSource 

type EventSource = httpapi.AddressEventSource

EventSource is an alias for the API-generated type, making openapi.yaml the single source of truth for valid values. It records which subsystem wrote an address event; EventTrigger records what set it off.

type EventTrigger added in v0.7.0 

type EventTrigger = httpapi.AddressEventTrigger

EventTrigger is an alias for the API-generated type, making openapi.yaml the single source of truth for valid values. It is orthogonal to EventSource: the same subsystem writes events for different reasons, and the pairing is always a caller decision — a heartbeat can be scheduled or user-pressed, so neither axis may be derived from the other.

func ParseEventTrigger added in v0.7.0 

func ParseEventTrigger(v string) (EventTrigger, bool)

ParseEventTrigger maps a caller-supplied trigger onto a value safe to store. It takes a raw string rather than the enum because the heartbeat endpoints deliberately declare the parameter untyped: a value the request validator would reject costs the device its authorization, and a heartbeat must never fail over its own annotation. So an unrecognised value degrades here, as does EventTriggerSystem, which is server-set and not claimable over the wire. The bool reports whether v was recognised, so the caller can warn without deciding the fallback itself. An absent parameter is the caller's own case to handle: it is an ordinary older-client heartbeat, not something to warn about.

type FleetRow added in v0.6.0 

type FleetRow struct {
	OwnerID ids.UserID
	Device  httpapi.FleetDevice
}

FleetRow is one device in list shape, tagged with its owner so a composer can group without a second lookup. Rules and pairing are attached by the composer from the domains that own them.

type GeoResolver added in v0.6.0 

type GeoResolver interface {
	Resolve(ip string) geoip.Result
}

GeoResolver resolves an IP to geographic and ASN data. Declared on the consumer side (Go convention); *geoip.Lookup satisfies it. A nil resolver is valid — enrichment is skipped.

type HTTPHandler 

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

func NewHTTPHandler 

func NewHTTPHandler(service *Service, repo *Repository, geo GeoResolver, logger *slog.Logger) *HTTPHandler

func (*HTTPHandler) APIKeyAuthenticator 

func (h *HTTPHandler) APIKeyAuthenticator() APIKeyAuthenticator

func (*HTTPHandler) AddAddress 

func (h *HTTPHandler) AddAddress(ctx context.Context, request httpapi.AddAddressRequestObject) (httpapi.AddAddressResponseObject, error)

func (*HTTPHandler) CreateDevice 

func (h *HTTPHandler) CreateDevice(ctx context.Context, request httpapi.CreateDeviceRequestObject) (httpapi.CreateDeviceResponseObject, error)

func (*HTTPHandler) DeleteDevice 

func (h *HTTPHandler) DeleteDevice(ctx context.Context, request httpapi.DeleteDeviceRequestObject) (httpapi.DeleteDeviceResponseObject, error)

func (*HTTPHandler) DeleteDeviceAPIKey added in v0.3.0 

func (h *HTTPHandler) DeleteDeviceAPIKey(ctx context.Context, request httpapi.DeleteDeviceAPIKeyRequestObject) (httpapi.DeleteDeviceAPIKeyResponseObject, error)

func (*HTTPHandler) DeviceHeartbeat 

func (h *HTTPHandler) DeviceHeartbeat(ctx context.Context, request httpapi.DeviceHeartbeatRequestObject) (httpapi.DeviceHeartbeatResponseObject, error)

func (*HTTPHandler) DeviceHeartbeatByAPIKey 

func (h *HTTPHandler) DeviceHeartbeatByAPIKey(ctx context.Context, request httpapi.DeviceHeartbeatByAPIKeyRequestObject) (httpapi.DeviceHeartbeatByAPIKeyResponseObject, error)

func (*HTTPHandler) DisableAddress 

func (h *HTTPHandler) DisableAddress(ctx context.Context, request httpapi.DisableAddressRequestObject) (httpapi.DisableAddressResponseObject, error)

func (*HTTPHandler) DisableDevice added in v0.4.0 

func (h *HTTPHandler) DisableDevice(ctx context.Context, request httpapi.DisableDeviceRequestObject) (httpapi.DisableDeviceResponseObject, error)

func (*HTTPHandler) EnableDevice added in v0.4.0 

func (h *HTTPHandler) EnableDevice(ctx context.Context, request httpapi.EnableDeviceRequestObject) (httpapi.EnableDeviceResponseObject, error)

func (*HTTPHandler) GetAddressHistory 

func (h *HTTPHandler) GetAddressHistory(
	ctx context.Context,
	request httpapi.GetAddressHistoryRequestObject,
) (httpapi.GetAddressHistoryResponseObject, error)

func (*HTTPHandler) GetAddressHistoryHistogram added in v0.6.0 

func (h *HTTPHandler) GetAddressHistoryHistogram(
	ctx context.Context,
	request httpapi.GetAddressHistoryHistogramRequestObject,
) (httpapi.GetAddressHistoryHistogramResponseObject, error)

func (*HTTPHandler) GetAddressHistoryTuning added in v0.7.0 

func (h *HTTPHandler) GetAddressHistoryTuning(
	ctx context.Context,
	request httpapi.GetAddressHistoryTuningRequestObject,
) (httpapi.GetAddressHistoryTuningResponseObject, error)

func (*HTTPHandler) GetDeviceAddresses added in v0.6.0 

func (h *HTTPHandler) GetDeviceAddresses(
	ctx context.Context,
	request httpapi.GetDeviceAddressesRequestObject,
) (httpapi.GetDeviceAddressesResponseObject, error)

func (*HTTPHandler) ListDeviceRefs added in v0.6.0 

func (h *HTTPHandler) ListDeviceRefs(
	ctx context.Context,
	_ httpapi.ListDeviceRefsRequestObject,
) (httpapi.ListDeviceRefsResponseObject, error)

func (*HTTPHandler) RegenerateDeviceAPIKey 

func (h *HTTPHandler) RegenerateDeviceAPIKey(ctx context.Context, request httpapi.RegenerateDeviceAPIKeyRequestObject) (httpapi.RegenerateDeviceAPIKeyResponseObject, error)

func (*HTTPHandler) UpdateDevice added in v0.2.0 

func (h *HTTPHandler) UpdateDevice(ctx context.Context, request httpapi.UpdateDeviceRequestObject) (httpapi.UpdateDeviceResponseObject, error)

type IPEntry 

type IPEntry struct {
	IP        string        `db:"ip"`
	DeviceID  ids.DeviceID  `db:"device_id"`
	AddressID ids.AddressID `db:"address_id"`
	UserID    ids.UserID    `db:"user_id"`
}

IPEntry associates an enabled IP address with the device, address, and owning user. All enabled rows are returned (multiple per IP when devices share an address); the policy layer merges them with deny-wins intersection.

type Principal 

type Principal struct {
	DeviceID ids.DeviceID
}

func NewPrincipal 

func NewPrincipal(deviceID ids.DeviceID) *Principal

func PrincipalFromContext 

func PrincipalFromContext(ctx context.Context) (*Principal, bool)

func PrincipalFromDevice 

func PrincipalFromDevice(device *Device) *Principal

type Repository 

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

func NewRepository 

func NewRepository(db *database.DB) *Repository

func (*Repository) CheckAddressOwnership 

func (r *Repository) CheckAddressOwnership(ctx context.Context, deviceID ids.DeviceID, addressID ids.AddressID) error

func (*Repository) CreateAddress 

func (r *Repository) CreateAddress(ctx context.Context, params CreateAddressParams, source EventSource, trigger EventTrigger) (*Address, error)

func (*Repository) CreateDevice 

func (r *Repository) CreateDevice(ctx context.Context, params CreateDeviceParams) (*Device, error)

func (*Repository) DeleteAPIKey added in v0.3.0 

func (r *Repository) DeleteAPIKey(ctx context.Context, deviceID ids.DeviceID) error

func (*Repository) DeleteAddressEventsOlderThan added in v0.4.0 

func (r *Repository) DeleteAddressEventsOlderThan(ctx context.Context, before time.Time) (int64, error)

DeleteAddressEventsOlderThan removes address_events rows with created_at before the given time. Returns the number of rows deleted.

func (*Repository) DeleteDevice 

func (r *Repository) DeleteDevice(ctx context.Context, deviceID ids.DeviceID) error

func (*Repository) DisableAddress 

func (r *Repository) DisableAddress(ctx context.Context, addressID ids.AddressID) (*Address, error)

DisableAddress turns off a single address. Only the web UI's address toggle reaches it, so its provenance is fixed here; the bulk DisableAddresses is what the expiry and address-limit jobs use.

func (*Repository) DisableAddresses 

func (r *Repository) DisableAddresses(ctx context.Context, addressIDs []ids.AddressID, source EventSource, trigger EventTrigger) ([]Address, error)

func (*Repository) EnableAddress 

func (r *Repository) EnableAddress(ctx context.Context, addressID ids.AddressID, source EventSource, trigger EventTrigger) (*Address, error)

func (*Repository) FleetRows added in v0.6.0 

func (r *Repository) FleetRows(ctx context.Context, ownerID *ids.UserID) ([]FleetRow, error)

FleetRows returns every non-deleted device in the device-list shape, ordered by name, optionally narrowed to one owner. This is the only query in the fleet composition that knows about owner scoping; everything downstream is keyed by device id.

func (*Repository) GetAddress 

func (r *Repository) GetAddress(ctx context.Context, addressID ids.AddressID) (*Address, error)

func (*Repository) GetAddressForDeviceByIP 

func (r *Repository) GetAddressForDeviceByIP(ctx context.Context, deviceID ids.DeviceID, ip netip.Addr) (*Address, error)

func (*Repository) GetAddressHistoryEvents added in v0.6.0 

func (r *Repository) GetAddressHistoryEvents(ctx context.Context, q AddressHistoryQuery) (AddressHistoryEvents, error)

GetAddressHistoryEvents returns a keyset-paginated page of address events, newest first, plus the total matching the filters.

func (*Repository) GetAddressHistoryHistogram added in v0.6.0 

func (r *Repository) GetAddressHistoryHistogram(ctx context.Context, q AddressHistoryQuery) (httpapi.AddressHistoryHistogramResponse, error)

GetAddressHistoryHistogram answers the histogram endpoint: per-bucket device counts across all four TTL-risk bands, contiguous across the whole window. Granularity is chosen server-side from the window size.

func (*Repository) GetAddressHistoryTuning added in v0.7.0 

func (r *Repository) GetAddressHistoryTuning(ctx context.Context, q AddressHistoryTuningQuery) (httpapi.AddressHistoryTuningResponse, error)

GetAddressHistoryTuning answers the tuning endpoint: with no device_id, a top-5 ranking of every device whose TTL is genuinely too short in the window; with device_id, that one device's readout regardless of whether it meets the ranking threshold.

func (*Repository) GetDevice 

func (r *Repository) GetDevice(ctx context.Context, id ids.DeviceID) (*Device, error)

func (*Repository) GetDeviceAddresses added in v0.6.0 

func (r *Repository) GetDeviceAddresses(ctx context.Context, deviceID ids.DeviceID) ([]AddressView, error)

func (*Repository) GetDeviceByAPIKeyHash 

func (r *Repository) GetDeviceByAPIKeyHash(ctx context.Context, keyHash string) (*Device, error)

func (*Repository) GetDeviceIDsByOwner added in v0.4.0 

func (r *Repository) GetDeviceIDsByOwner(ctx context.Context, ownerID ids.UserID) ([]ids.DeviceID, error)

func (*Repository) GetDeviceRefs added in v0.6.0 

func (r *Repository) GetDeviceRefs(ctx context.Context) ([]httpapi.DeviceRef, error)

GetDeviceRefs returns every non-deleted device as a flat {id, name, owner_id} reference, for device pickers and the device→owner reverse map.

func (*Repository) GetEnabledAddressesForDevice added in v0.2.0 

func (r *Repository) GetEnabledAddressesForDevice(ctx context.Context, deviceID ids.DeviceID) ([]Address, error)

GetEnabledAddressesForDevice returns all enabled addresses for a device, ordered by updated_at DESC.

func (*Repository) GetEnabledIPEntries 

func (r *Repository) GetEnabledIPEntries(ctx context.Context) ([]IPEntry, error)

func (*Repository) IsDeviceDisabled added in v0.4.0 

func (r *Repository) IsDeviceDisabled(ctx context.Context, id ids.DeviceID) (bool, error)

IsDeviceDisabled reports whether a device has been disabled (disabled_at set). A missing or soft-deleted device returns ErrDeviceNotFound, so callers can use this as both an existence and a state check.

func (*Repository) RefreshAddress 

func (r *Repository) RefreshAddress(ctx context.Context, addressID ids.AddressID, source EventSource, trigger EventTrigger) (*Address, error)

RefreshAddress records activity for an already-enabled address

func (*Repository) SetDeviceDisabled added in v0.4.0 

func (r *Repository) SetDeviceDisabled(ctx context.Context, deviceID ids.DeviceID, disabled bool) error

SetDeviceDisabled flips a device's disabled state. When disabled is true the disabled_at timestamp is stamped; when false it is cleared (re-enabled).

func (*Repository) UpdateDevice added in v0.2.0 

func (r *Repository) UpdateDevice(ctx context.Context, device *Device) (*Device, error)

func (*Repository) UpsertAPIKey added in v0.3.0 

func (r *Repository) UpsertAPIKey(ctx context.Context, deviceID ids.DeviceID, keyHash string, keyPrefix string) error

type Service 

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

func NewService 

func NewService(repo repository, transactor transactor, logger *slog.Logger, trustedProxy netip.Addr) *Service

func (*Service) AddAddressObserver 

func (s *Service) AddAddressObserver(o AddressObserver)

func (*Service) AddDeviceObserver added in v0.6.0 

func (s *Service) AddDeviceObserver(o DeviceObserver)

func (*Service) Authenticate 

func (s *Service) Authenticate(ctx context.Context, rawKey string) (*Principal, error)

func (*Service) CreateDevice 

func (s *Service) CreateDevice(ctx context.Context, principal *auth.Principal, name string, requestedOwnerID *ids.UserID) (*Device, error)

CreateDevice creates a bare device (name + owner only). It is the primitive a device needs to exist; richer creation goes through CreateDeviceWithOptions.

func (*Service) CreateDeviceWithOptions added in v0.4.0 

func (s *Service) CreateDeviceWithOptions(ctx context.Context, principal *auth.Principal, input CreateDeviceInput) (*Device, string, error)

CreateDeviceWithOptions creates a device and, when requested, mints its API key in the same transaction so a "shown once" key is never stranded on a half-created device. The raw key is returned only when GenerateAPIKey is set. Pairing codes and address rules are provisioned separately on their own endpoints (a credential-less device is perfectly valid).

func (*Service) DeleteAPIKey added in v0.3.0 

func (s *Service) DeleteAPIKey(ctx context.Context, deviceID ids.DeviceID) error

func (*Service) DeleteDevice 

func (s *Service) DeleteDevice(ctx context.Context, deviceID ids.DeviceID) error

func (*Service) DisableAddress 

func (s *Service) DisableAddress(ctx context.Context, deviceID ids.DeviceID, addressID ids.AddressID) (*Address, error)

func (*Service) DisableAddresses 

func (s *Service) DisableAddresses(ctx context.Context, addressIDs []ids.AddressID, source EventSource, trigger EventTrigger) error

func (*Service) DisableDevice added in v0.4.0 

func (s *Service) DisableDevice(ctx context.Context, deviceID ids.DeviceID) (*Device, error)

DisableDevice is a reversible freeze: it disables every active address in one transaction (removing the device's IPs from the access allowlist) and stamps disabled_at, which blocks address enable/refresh until the device is re-enabled. The API key is deliberately kept — disable is a safety toggle, not a de-credentialing (use DeleteAPIKey for that). EnableDevice reverses it.

func (*Service) EnableDevice added in v0.4.0 

func (s *Service) EnableDevice(ctx context.Context, deviceID ids.DeviceID) (*Device, error)

EnableDevice reverses DisableDevice by clearing the disabled_at flag, which re-permits address enable/refresh. The device's API key was never removed, so it can heartbeat its addresses back to enabled on its next check-in; addresses disabled at freeze time are not re-enabled here.

func (*Service) GetDevice 

func (s *Service) GetDevice(ctx context.Context, deviceID ids.DeviceID) (*Device, error)

func (*Service) GetEnabledAddressesForDevice added in v0.2.0 

func (s *Service) GetEnabledAddressesForDevice(ctx context.Context, deviceID ids.DeviceID) ([]Address, error)

GetEnabledAddressesForDevice returns all enabled addresses for a device, ordered by updated_at DESC.

func (*Service) GetEnabledIPEntries 

func (s *Service) GetEnabledIPEntries(ctx context.Context) ([]IPEntry, error)

func (*Service) OnUserEvent added in v0.4.0 

func (s *Service) OnUserEvent(ctx context.Context, event auth.UserEvent)

OnUserEvent implements auth.UserObserver. On deletion it soft-deletes every device owned by the user and disables their addresses, firing the AddressDisabled events that trigger a policy cache refresh.

func (*Service) RegenerateAPIKey 

func (s *Service) RegenerateAPIKey(ctx context.Context, deviceID ids.DeviceID) (*Device, string, error)

func (*Service) RegisterAddressActivity 

func (s *Service) RegisterAddressActivity(ctx context.Context, deviceID ids.DeviceID, inputIP string, source EventSource, trigger EventTrigger) (*Address, AddressEventType, error)

func (*Service) UpdateDevice added in v0.2.0 

func (s *Service) UpdateDevice(ctx context.Context, deviceID ids.DeviceID, input UpdateDeviceInput) (*Device, error)

type TTLRisk added in v0.6.0 

type TTLRisk string

TTLRisk classifies how an event's renewal gap compares to the device's configured lease TTL. 

const (
	TTLRiskUnknown     TTLRisk = "unknown"
	TTLRiskOK          TTLRisk = "ok"
	TTLRiskApproaching TTLRisk = "approaching"
	TTLRiskCritical    TTLRisk = "critical"
	TTLRiskBreached    TTLRisk = "breached"
)

type UpdateDeviceInput added in v0.2.0 

type UpdateDeviceInput struct {
	Name        *string
	Description **string
	Icon        **string
	OwnerID     *ids.UserID
}

UpdateDeviceInput carries the raw nullable API values for a device profile update. nil pointer = field was absent in the request (leave unchanged). For Description and Icon, **string semantics apply: nil = absent, *nil = clear, *&s = set.

Source Files

View all Source files

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.