Documentation
¶
Overview ¶
Package appengine is the AppEngine API (docs/DESIGN.md §3.7, ROADMAP §8.2): the operator/application surface for device status, interface data queries, server-owned publishing, groups, and the live event socket. It is wire-shaped to upstream astarte_appengine_api so astartectl and applications work unmodified, reading through the store and writing server-owned values through the engine.
Index ¶
- Constants
- Variables
- type API
- type DevicePatch
- type DeviceStatus
- type QueryOpts
- type Sample
- type ServerData
- type Service
- func (s *Service) AddGroupDevice(ctx context.Context, realm, name, deviceID string) error
- func (s *Service) CreateGroup(ctx context.Context, realm, name string, devices []string) error
- func (s *Service) GetData(ctx context.Context, realm, deviceID, ifaceName, path string, opts QueryOpts) (any, error)
- func (s *Service) GetDevice(ctx context.Context, realm, deviceID string) (*DeviceStatus, error)
- func (s *Service) GetDeviceByAlias(ctx context.Context, realm, alias string) (*DeviceStatus, error)
- func (s *Service) ListDevices(ctx context.Context, realm string, after string, limit int) ([]string, string, error)
- func (s *Service) ListGroupDevices(ctx context.Context, realm, name string) ([]string, error)
- func (s *Service) ListGroups(ctx context.Context, realm string) ([]string, error)
- func (s *Service) PatchDevice(ctx context.Context, realm, deviceID string, p DevicePatch) (*DeviceStatus, error)
- func (s *Service) PublishData(ctx context.Context, realm, deviceID, ifaceName, path string, ...) error
- func (s *Service) RemoveGroupDevice(ctx context.Context, realm, name, deviceID string) error
- func (s *Service) UnsetProperty(ctx context.Context, realm, deviceID, ifaceName, path string) error
Constants ¶
const DefaultDeviceLimit = 100
DefaultDeviceLimit is the device-list page size when the caller gives none.
Variables ¶
var ErrValidation = errors.New("appengine: validation failed")
ErrValidation wraps a well-formed request that violates a rule (maps to 422).
Functions ¶
This section is empty.
Types ¶
type API ¶
type API struct {
// contains filtered or unexported fields
}
API is the /appengine/v1 HTTP surface (docs/ROADMAP.md §8.2 file 7.8), guarded by a realm JWT carrying a_aea.
type DevicePatch ¶
type DevicePatch struct {
Aliases map[string]*string
Attributes map[string]*string
CredentialsInhibited *bool
}
DevicePatch carries the JSON-merge-style PATCH fields (upstream DevicePatch): a nil pointer leaves a field unchanged, a present map patches aliases/attributes (a nil map value removes that key).
type DeviceStatus ¶
type DeviceStatus struct {
ID string `json:"id"`
Connected bool `json:"connected"`
Introspection map[string]introspectionEntry `json:"introspection"`
Aliases map[string]string `json:"aliases"`
Attributes map[string]string `json:"attributes"`
Groups []string `json:"groups"`
CredentialsInhibited bool `json:"credentials_inhibited"`
TotalReceivedMsgs int64 `json:"total_received_msgs"`
TotalReceivedBytes int64 `json:"total_received_bytes"`
FirstRegistration *time.Time `json:"first_registration"`
FirstCredentialsReq *time.Time `json:"first_credentials_request"`
LastConnection *time.Time `json:"last_connection"`
LastDisconnection *time.Time `json:"last_disconnection"`
LastSeenIP string `json:"last_seen_ip,omitempty"`
PreviousInterfaces map[string]introspectionEntry `json:"previous_interfaces,omitempty"`
}
DeviceStatus is the AppEngine device status body (upstream DeviceStatusView): a JSON-friendly projection of a devices row.
type QueryOpts ¶
type QueryOpts struct {
Since *time.Time
SinceAfter *time.Time
To *time.Time
Limit int
Descending bool
DownsampleTo *time.Duration
}
QueryOpts are the datastream query parameters (upstream since/since_after/to/limit/downsample_to). The zero value reads the whole series ascending.
type ServerData ¶
type ServerData interface {
PublishServerValue(ctx context.Context, realm string, id deviceid.ID, iface, path string, value json.RawMessage, ts *time.Time) error
UnsetServerProperty(ctx context.Context, realm string, id deviceid.ID, iface, path string) error
}
ServerData is the engine port for server-owned writes (docs/ROADMAP.md §8.2 file 7.7). *engine.Engine satisfies it; tests substitute a fake.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service implements the AppEngine business logic over the store and engine.
func NewService ¶
NewService builds the service. sd may be nil (read-only deployments); log defaults to slog.Default().
func (*Service) AddGroupDevice ¶
AddGroupDevice adds a device to a group.
func (*Service) CreateGroup ¶
CreateGroup creates a group with its initial device membership (upstream POST /groups requires a non-empty device list).
func (*Service) GetData ¶
func (s *Service) GetData(ctx context.Context, realm, deviceID, ifaceName, path string, opts QueryOpts) (any, error)
GetData reads an interface endpoint (upstream GET .../interfaces/{iface} [/{path}]), dispatching on the interface type: a datastream series (with the query options) or a properties snapshot.
func (*Service) GetDeviceByAlias ¶
GetDeviceByAlias returns the status of the device owning an alias (upstream GET /devices-by-alias/{alias}).
func (*Service) ListDevices ¶
func (s *Service) ListDevices(ctx context.Context, realm string, after string, limit int) ([]string, string, error)
ListDevices returns one page of device IDs (upstream GET /devices). after is the cursor (exclusive); limit <= 0 selects DefaultDeviceLimit. The second result is the next-page cursor, or "" at the end.
func (*Service) ListGroupDevices ¶
ListGroupDevices returns the device IDs in a group.
func (*Service) ListGroups ¶
ListGroups returns the realm's group names.
func (*Service) PatchDevice ¶
func (s *Service) PatchDevice(ctx context.Context, realm, deviceID string, p DevicePatch) (*DeviceStatus, error)
PatchDevice applies a device patch (upstream PATCH /devices/{id}).
func (*Service) PublishData ¶
func (s *Service) PublishData(ctx context.Context, realm, deviceID, ifaceName, path string, value json.RawMessage, ts *time.Time) error
PublishData writes a server-owned value (upstream PUT/POST .../interfaces/{iface}/{path}) through the engine. value is the unwrapped "data" JSON; ts is the optional explicit timestamp.
func (*Service) RemoveGroupDevice ¶
RemoveGroupDevice removes a device from a group.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package stream is the AppEngine live event socket (docs/DESIGN.md §3.7, §1.1 deviation; ROADMAP §8.2 file 7.9): a WebSocket (with an SSE fallback) at /astrate/v1/{realm}/socket fed by the engine's in-process fan-out bus.
|
Package stream is the AppEngine live event socket (docs/DESIGN.md §3.7, §1.1 deviation; ROADMAP §8.2 file 7.9): a WebSocket (with an SSE fallback) at /astrate/v1/{realm}/socket fed by the engine's in-process fan-out bus. |