api

package
v0.2.29 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package api 定义 edge↔server↔浏览器 的共享契约：WS 消息信封与 REST DTO。 两侧二进制都只认这里的类型 —— 契约变更必须同时过前端 lib/types.ts。

Index

Constants

View Source 
const (
	PluginAckApplied  = "applied"
	PluginAckRejected = "rejected"
	PluginAckFailed   = "failed"
)

Plugin ack 稳定状态值。

View Source 
const (
	PluginErrNotFound          = "plugin_instance_not_found"
	PluginErrConflict          = "plugin_instance_conflict"
	PluginErrQuota             = "plugin_quota_exceeded"
	PluginErrPermissionConfirm = "plugin_permission_confirmation_required"
	PluginErrEdgeOffline       = "plugin_edge_offline"
	PluginErrSecretForbidden   = "plugin_secret_forbidden"
	PluginErrInvalidConfig     = "plugin_invalid_config"
	PluginErrStoreUnavailable  = "plugin_store_unavailable"
	PluginErrKindUnavailable   = "plugin_instance_kind_unavailable"
	PluginErrHostMismatch      = "plugin_instance_host_mismatch"
	PluginErrKindUnsupported   = "plugin_instance_kind_unsupported"
)

插件实例写操作的稳定错误码。前端按码呈现，不解析错误文本。

View Source 
const (
	APIErrInvalidRequest              = "invalid_request"
	APIErrInvalidCredentials          = "invalid_credentials"
	APIErrInvalidRole                 = "invalid_role"
	APIErrInvalidScopes               = "invalid_scopes"
	APIErrAuthenticationRequired      = "authentication_required"
	APIErrPermissionDenied            = "permission_denied"
	APIErrWriteForbidden              = "write_forbidden"
	APIErrNotFound                    = "not_found"
	APIErrConflict                    = "conflict"
	APIErrRateLimited                 = "rate_limited"
	APIErrStoreUnavailable            = "store_unavailable"
	APIErrInternal                    = "internal_error"
	APIErrSetupForbidden              = "setup_forbidden"
	APIErrSetupAlreadyComplete        = "setup_already_complete"
	APIErrUsernameConflict            = "username_conflict"
	APIErrUserNotFound                = "user_not_found"
	APIErrLastAdminProtected          = "last_admin_protected"
	APIErrTokenNotFound               = "token_not_found"
	APIErrPluginCatalogUnavailable    = "plugin_catalog_unavailable"
	APIErrPluginNotFound              = "plugin_not_found"
	APIErrDeviceNotFound              = "device_not_found"
	APIErrEdgeOffline                 = "edge_offline"
	APIErrUnsupportedCommand          = "unsupported_command"
	APIErrCommandDeliveryFailed       = "command_delivery_failed"
	APIErrPluginUIAssetNotFound       = "plugin_ui_asset_not_found"
	APIErrPluginUIAssetForbidden      = "plugin_ui_asset_forbidden"
	APIErrPluginUIAssetTypeNotAllowed = "plugin_ui_asset_type_not_allowed"
	APIErrPluginUIAssetTooLarge       = "plugin_ui_asset_too_large"
	APIErrApplicationUnavailable      = "application_unavailable"
	APIErrApplicationRejected         = "application_rejected"
	APIErrJobNotFound                 = "job_not_found"
	APIErrInvalidIdempotencyKey       = "invalid_idempotency_key"
	APIErrInvalidArgs                 = "invalid_args"
	APIErrInvalidPluginResponse       = "invalid_plugin_response"
)

API 稳定错误码。新增错误必须先在此注册，再通过 writeAPIError 输出。

View Source 
const Version = 1

Version 是消息信封协议版本，不兼容变更时递增。

Variables

This section is empty.

Functions

func DeviceKey 

func DeviceKey(edgeID, deviceID string) string

DeviceKey 拼 "<edge_id>/<device_id>"。

func IsKnownErrorCode added in v0.2.23 

func IsKnownErrorCode(code string) bool

IsKnownErrorCode 报告 code 是否属于已注册的 canonical 错误码。

Types

type AckData 

type AckData struct {
	CommandID int64  `json:"command_id"`
	Status    string `json:"status"`
	Detail    string `json:"detail,omitempty"`
}

AckData 是命令回执。Status ∈ sent|ok|failed|timeout。

type AdapterView 

type AdapterView struct {
	Name     string   `json:"name"`
	Commands []string `json:"commands"`
}

AdapterView 描述一个已注册的设备适配器及其命令白名单。 前端命令面板以此为唯一事实源，新增适配器无需改前端。

type AppBindingView added in v0.2.7 

type AppBindingView struct {
	RequirementID string `json:"requirement_id"`
	Capability    string `json:"capability"`
	EntityID      string `json:"entity_id"`
}

AppBindingView 是一个 Application 实例的 Capability 绑定投影（运行态）。 绑定在实例启动时由 Binder 权威匹配，只在实例运行期间存在。

type AppBindingsView added in v0.2.7 

type AppBindingsView struct {
	InstanceID string           `json:"instance_id"`
	Running    bool             `json:"running"`
	Bindings   []AppBindingView `json:"bindings"`
}

AppBindingsView 是 GET /api/plugin-instances/{id}/bindings 响应。 Running=false 表示 AppHost 未启用或实例未在运行——绑定是运行态，非持久态。

type AppDomainRecordView added in v0.2.7 

type AppDomainRecordView struct {
	RecordType string `json:"record_type"`
	RecordID   string `json:"record_id"`
	DataJSON   string `json:"data_json"`
	Version    string `json:"version,omitempty"`
	UpdatedAt  int64  `json:"updated_at"` // unix 秒
}

AppDomainRecordView 是领域记录 REST 行。

type AppDomainRecordsView added in v0.2.7 

type AppDomainRecordsView struct {
	InstanceID string                `json:"instance_id"`
	Records    []AppDomainRecordView `json:"records"`
	RecordType string                `json:"record_type,omitempty"` // 生效的过滤条件
	Limit      int                   `json:"limit"`
	Offset     int                   `json:"offset"`
}

AppDomainRecordsView 是 GET /api/plugin-instances/{id}/records 响应。 空列表与「实例不存在于本租户」同形：跨租户探测得不到存在性信息。

type AppJobRunRequest added in v0.2.15 

type AppJobRunRequest struct {
	ArgsJSON       string `json:"args_json"`
	IdempotencyKey string `json:"idempotency_key"`
}

AppJobRunRequest invokes a declared manual job with a caller-stable retry key.

type AppJobRunView added in v0.2.15 

type AppJobRunView struct {
	InstanceID string `json:"instance_id"`
	JobID      string `json:"job_id"`
	ResultJSON string `json:"result_json"`
}

type AppJobView added in v0.2.15 

type AppJobView struct {
	ID              string `json:"id"`
	Title           string `json:"title"`
	InputSchemaJSON string `json:"input_schema_json"`
	ManualOnly      bool   `json:"manual_only"`
}

AppJobView is the runtime declaration, not a platform-owned action list.

type AppJobsView added in v0.2.7 

type AppJobsView struct {
	InstanceID     string                `json:"instance_id"`
	Running        bool                  `json:"running"`
	Jobs           []string              `json:"jobs"`
	Scheduled      []AppScheduledJobView `json:"scheduled"`
	JobDescriptors []AppJobView          `json:"job_descriptors"`
}

AppJobsView 是 GET /api/plugin-instances/{id}/jobs 响应。 Jobs 为应用声明并注册到分钟调度的 job id（运行态投影）； Scheduled 为 D2 Durable Scheduler 的声明式 cron 任务（持久态）。

type AppScheduledJobView added in v0.2.8 

type AppScheduledJobView struct {
	ScheduleID   string `json:"schedule_id"`
	Cron         string `json:"cron"`
	Timezone     string `json:"timezone"`
	MissedPolicy string `json:"missed_policy"`
	NextRunAt    int64  `json:"next_run_at,omitempty"` // unix 秒
	LastRunAt    int64  `json:"last_run_at,omitempty"` // unix 秒
	State        string `json:"state"`
	Revision     int64  `json:"revision"`
}

AppScheduledJobView 是一条声明式 cron 任务（schedule_job 效果声明，DB 持久）。

type CapabilitiesData added in v0.2.2 

type CapabilitiesData struct {
	Sources []CapabilitySource `json:"sources"`
}

CapabilitiesData 是 edge→server 的 Capability 文档上报载荷，**全量覆盖**语义： 一次上报就是本 Edge 当前全部声明者，Server 整体替换该 Edge 的文档集。 没有增量/删除消息，因此插件停用或卸载后不会在 catalog 里留下幽灵能力。

为什么需要这条通道：外部 Driver 的能力文档（标题/属性/事件/action inputSchema） 只存在于 Edge 侧插件进程里，而 /api/capabilities 与前端 Schema 驱动 UI 都跑在 Server 侧。缺了它，装了新 Driver 的设备在 WebUI 上只有裸观测值、没有命令面板。

type CapabilitySource added in v0.2.2 

type CapabilitySource struct {
	Source       string             `json:"source"`
	Capabilities []model.Capability `json:"capabilities"`
}

CapabilitySource 是一个 Capability 文档声明者：外部 Driver Plugin 的 driver ID， 或进程内适配器名。Server 只按声明者归组存储，不解释其中任何硬件语义。 Actions 的 destructive/confirmation 与 inputSchema 同属公开契约，须保留到 REST 读面。

type CommandData 

type CommandData struct {
	CommandID int64  `json:"command_id"`
	Cmd       string `json:"cmd"`
	Args      string `json:"args,omitempty"`
}

CommandData 是 server→edge 命令。Cmd 由设备适配器/驱动声明并通过命令白名单 校验；平台不解释具体硬件语义。

type CommandHandledRequest added in v0.2.25 

type CommandHandledRequest struct {
	IDs          []int64 `json:"ids,omitempty"`
	AllUnhandled bool    `json:"all_unhandled,omitempty"`
}

CommandHandledRequest 将失败/超时操作标记为已处理。 ids 用于单条/批量处理；all_unhandled 用于清空当前 24 小时窗口内的未处理失败项。

type CommandView 

type CommandView struct {
	ID        int64  `json:"id"`
	DeviceID  string `json:"device_id"`
	Cmd       string `json:"cmd"`
	Args      string `json:"args"`
	Status    string `json:"status"`
	CreatedAt int64  `json:"created_at"`
	AckedAt   int64  `json:"acked_at"`
	Result    string `json:"result"`
	HandledAt int64  `json:"handled_at,omitempty"`
}

CommandView 是命令行。

type DeviceMeta 

type DeviceMeta struct {
	ID      string `json:"id"`
	Adapter string `json:"adapter"`
	Name    string `json:"name,omitempty"`
	Port    string `json:"port,omitempty"`
}

DeviceMeta 描述 edge 所辖设备的静态信息。

type DeviceView 

type DeviceView struct {
	ID        string         `json:"id"`
	EdgeID    string         `json:"edge_id"`
	Adapter   string         `json:"adapter"`
	Name      string         `json:"name,omitempty"`
	Port      string         `json:"port,omitempty"`
	Online    bool           `json:"online"`
	State     map[string]any `json:"state"`
	UpdatedAt int64          `json:"updated_at"`
	LastSeen  int64          `json:"last_seen"`
}

DeviceView 是 REST/WS 的设备视图。

type DomainRecordData added in v0.2.7 

type DomainRecordData struct {
	InstanceID string `json:"instance_id"`
	RecordType string `json:"record_type"`
	RecordID   string `json:"record_id"`
	DataJSON   string `json:"data_json"`
	Version    string `json:"version,omitempty"`
	UpdatedAt  int64  `json:"updated_at"` // unix 秒
	Created    bool   `json:"created"`
}

DomainRecordData 是领域记录 WS 投影载荷。created=true 表示首次写入， false 表示同键覆盖（upsert 语义）。Device 字段为空——记录属于应用实例， 不属于设备；消费端按 instance_id + record_type + record_id 定位。

type EdgeUpData 

type EdgeUpData struct {
	EdgeID  string   `json:"edge_id"`
	Devices []string `json:"devices"`
	Version string   `json:"version"`
}

EdgeUpData 是 edge 上/下线广播载荷（edge_down 复用同一结构）。 与前端 lib/types.ts 的 EdgeUpData 一一对应。

type EdgeView 

type EdgeView struct {
	EdgeID      string   `json:"edge_id"`
	Online      bool     `json:"online"`
	Version     string   `json:"version"`
	Devices     []string `json:"devices"`
	ConnectedAt int64    `json:"connected_at"`
}

EdgeView 是边缘节点视图。

type EntityObservationSet added in v0.2.15 

type EntityObservationSet struct {
	EntityID     string                       `json:"entity_id"`
	Observations map[string]model.Observation `json:"observations"`
}

EntityObservationSet is one entity's real sampled properties, not a command or a domain event.

type Envelope 

type Envelope struct {
	V      int             `json:"v"`
	Type   MsgType         `json:"type"`
	Device string          `json:"device,omitempty"`
	Ts     int64           `json:"ts"` // unix 秒
	Data   json.RawMessage `json:"data,omitempty"`
}

Envelope 是统一 WS 消息信封。Device 格式为 "<edge_id>/<device_id>"。

type ErrorResponse added in v0.2.23 

type ErrorResponse struct {
	Error     string         `json:"error"`
	Code      string         `json:"code"`
	Message   string         `json:"message"`
	RequestID string         `json:"request_id"`
	Params    map[string]any `json:"params,omitempty"`
}

ErrorResponse 是所有 JSON API 失败的规范响应体。Error 与 Code 保留同一稳定码， Message 只用于日志、诊断和旧客户端兼容；新 UI 必须按 Code + Params 本地化。

type EventData 

type EventData struct {
	Type string `json:"type"`
	// EntityID 是事件归属实体（可为空：设备级事件）。Capability 绑定按它路由，
	// 是 Application Plugin 收到正确实体事件的依据。
	EntityID string `json:"entity_id,omitempty"`
	Label    string `json:"label,omitempty"`
}

EventData 是设备事件。Type 是设备适配器/驱动声明的规范化事件标签， 平台只按契约搬运，不解释具体硬件语义。

type EventView 

type EventView struct {
	ID       int64  `json:"id"`
	DeviceID string `json:"device_id"`
	Ts       int64  `json:"ts"`
	Type     string `json:"type"`
	Payload  string `json:"payload"`
}

EventView 是事件历史行。

type HealthView 

type HealthView struct {
	OK            bool   `json:"ok"`
	Version       string `json:"version"`
	UptimeS       int64  `json:"uptime_s"`
	DevicesOnline int    `json:"devices_online"`
	DevicesTotal  int    `json:"devices_total"`
	EdgesOnline   int    `json:"edges_online"`
}

HealthView 是 /healthz 载荷。

type HelloData 

type HelloData struct {
	EdgeID  string       `json:"edge_id"`
	Token   string       `json:"token,omitempty"`
	Version string       `json:"version"`
	Tenant  string       `json:"tenant,omitempty"` // 缺省 default（docs/api.md §3 P2）
	Devices []DeviceMeta `json:"devices"`
}

HelloData 是 edge 注册载荷。

type MsgType 

type MsgType string

MsgType 枚举 WS 消息类型。 

const (
	MsgHello         MsgType = "hello"          // edge→server：鉴权+注册
	MsgSnapshot      MsgType = "snapshot"       // server→浏览器：连接时的全量快照
	MsgState         MsgType = "state"          // edge→server→浏览器：设备状态
	MsgEvent         MsgType = "event"          // edge→server→浏览器：设备事件
	MsgCommand       MsgType = "command"        // server→edge：命令下发
	MsgCommandAck    MsgType = "command_ack"    // edge→server→浏览器：命令回执
	MsgEdgeUp        MsgType = "edge_up"        // server→浏览器：edge 上线
	MsgEdgeDown      MsgType = "edge_down"      // server→浏览器：edge 离线
	MsgDescriptor    MsgType = "descriptor"     // edge→server→浏览器：设备 Descriptor
	MsgPluginStatus  MsgType = "plugin_status"  // edge→server：插件安装/实例实际态全量快照
	MsgPluginDesired MsgType = "plugin_desired" // server→edge：租户/edge 插件期望态全量快照
	MsgPluginAck     MsgType = "plugin_ack"     // edge→server：期望态 revision 应用结果
	MsgCapabilities  MsgType = "capabilities"   // edge→server：Capability 文档全量上报（外部 Driver 的能力说明）
	MsgDomainRecord  MsgType = "domain_record"  // server→浏览器：Application 领域记录投影（created/updated）
	MsgPing          MsgType = "ping"
	MsgPong          MsgType = "pong"
)

type OverviewView 

type OverviewView struct {
	DevicesOnline  int           `json:"devices_online"`
	DevicesTotal   int           `json:"devices_total"`
	EdgesOnline    int           `json:"edges_online"`
	EdgesTotal     int           `json:"edges_total"`
	PluginsActive  int           `json:"plugins_active"`
	PluginsDesired int           `json:"plugins_desired"`
	CommandsFailed int           `json:"commands_failed"`
	RecentEvents   []EventView   `json:"recent_events"`
	OfflineDevices []DeviceView  `json:"offline_devices"`
	FailedCommands []CommandView `json:"failed_commands"`
	ServerTime     int64         `json:"server_time"`
}

OverviewView 是 WebUI Overview 页的一次性聚合读面。 所有计数都来自真实 edge 上报与 Server 权威态，禁止用占位/假数据填充。 CommandsFailed 为 [ServerTime-86400, ServerTime] 内 failed/timeout 的完整计数； FailedCommands 取同窗最新20条，失败时间为 acked_at（缺失时 created_at）。

type PluginAckData 

type PluginAckData struct {
	Revision       uint64                  `json:"revision"`
	SnapshotDigest string                  `json:"snapshot_digest"`
	Status         string                  `json:"status"`
	Results        []PluginApplyResultData `json:"results,omitempty"`
}

PluginAckData 是 Edge→Server 的 revision 应用结果。只有 Applied 才允许 Server 推进 applied_revision；Rejected/Failed 保持上一完整 revision。

type PluginApplicationContributionData 

type PluginApplicationContributionData struct {
	ID    string            `json:"id"`
	Title string            `json:"title,omitempty"`
	I18n  map[string]string `json:"i18n,omitempty"`
	UI    *PluginUIData     `json:"ui,omitempty"`
}

PluginApplicationContributionData 是 Application 插件对外贡献的稳定公开元数据。

type PluginApplyResultData 

type PluginApplyResultData struct {
	InstanceID string `json:"instance_id"`
	Status     string `json:"status"`
	Detail     string `json:"detail,omitempty"`
}

PluginApplyResultData 是单实例 reconcile 结果。Detail 必须有长度上限并经过脱敏。

type PluginConnectorContributionData 

type PluginConnectorContributionData struct {
	ID        string            `json:"id"`
	Title     string            `json:"title,omitempty"`
	I18n      map[string]string `json:"i18n,omitempty"`
	Direction string            `json:"direction,omitempty"`
	Host      string            `json:"host,omitempty"`
}

PluginConnectorContributionData 是 Connector 插件对外贡献的稳定公开元数据。

type PluginContributionsData 

type PluginContributionsData struct {
	Drivers      []PluginDriverContributionData      `json:"drivers,omitempty"`
	Applications []PluginApplicationContributionData `json:"applications,omitempty"`
	Connectors   []PluginConnectorContributionData   `json:"connectors,omitempty"`
}

PluginContributionsData 汇总一个安装物提供的贡献。它只含公开 manifest 字段。

type PluginDesiredData 

type PluginDesiredData struct {
	Revision       uint64                      `json:"revision"`
	SnapshotDigest string                      `json:"snapshot_digest"`
	Instances      []PluginDesiredInstanceData `json:"instances"`
}

PluginDesiredData 是 Server→Edge 的声明式全量期望态快照。 SnapshotDigest 绑定同 revision 的规范化 payload，防止同 revision 不同内容被接受。

type PluginDesiredInstanceData 

type PluginDesiredInstanceData struct {
	InstanceID string            `json:"instance_id"`
	PluginID   string            `json:"plugin_id"`
	Version    string            `json:"version"`
	Enabled    bool              `json:"enabled"`
	Isolation  string            `json:"isolation"`
	Config     map[string]string `json:"config,omitempty"`
}

PluginDesiredInstanceData 是 Server 权威期望态中的一个实例。 Config 值只允许非敏感标量或 secret://<name> handle；不得携带明文 secret。

type PluginDriverContributionData 

type PluginDriverContributionData struct {
	ID        string            `json:"id"`
	Title     string            `json:"title,omitempty"`
	I18n      map[string]string `json:"i18n,omitempty"`
	Discovery string            `json:"discovery,omitempty"`
	UI        *PluginUIData     `json:"ui,omitempty"`
}

PluginDriverContributionData 是 Driver 插件对外贡献的稳定公开元数据。

type PluginInstallationStatusData 

type PluginInstallationStatusData struct {
	PluginID          string                  `json:"plugin_id"`
	Version           string                  `json:"version"`
	Kind              string                  `json:"kind"`
	Protocol          int                     `json:"protocol"`
	Digest            string                  `json:"digest"`
	TrustMode         string                  `json:"trust_mode"`
	Verified          bool                    `json:"verified"`
	VerifiedPublisher string                  `json:"verified_publisher,omitempty"`
	Permissions       PluginPermissionsData   `json:"permissions"`
	Contributions     PluginContributionsData `json:"contributions"`
	Capabilities      []string                `json:"capabilities,omitempty"`
}

PluginInstallationStatusData 是 Edge 上报的已安装插件公开事实。 禁止添加本地路径、启动参数、环境变量或 secret 值。

type PluginInstanceActionRequest 

type PluginInstanceActionRequest struct {
	Force bool `json:"force,omitempty"`
}

PluginInstanceActionRequest 是 POST /api/plugin-instances/{id}/reconcile 的载荷。

type PluginInstanceCreateRequest 

type PluginInstanceCreateRequest struct {
	EdgeID     string            `json:"edge_id"`
	InstanceID string            `json:"instance_id"`
	PluginID   string            `json:"plugin_id"`
	Version    string            `json:"version"`
	Enabled    *bool             `json:"enabled,omitempty"`
	Isolation  string            `json:"isolation,omitempty"`
	Config     map[string]string `json:"config,omitempty"`
	SecretRefs []string          `json:"secret_refs,omitempty"`
	// ConfirmPermissions 为 true 时表示调用者已确认插件权限扩大；
	// 缺省 false 时权限扩大请求必须被拒绝且不产生新 revision。
	ConfirmPermissions bool `json:"confirm_permissions,omitempty"`
}

PluginInstanceCreateRequest 是 POST /api/plugin-instances 的载荷。 Config 值只允许非敏感标量或 secret://<name> handle；明文 secret 一律拒绝。

type PluginInstanceDeleteRequest 

type PluginInstanceDeleteRequest struct {
	Purge bool `json:"purge,omitempty"`
}

PluginInstanceDeleteRequest 是 DELETE /api/plugin-instances/{id} 的载荷。 默认保留插件数据；只有显式 Purge=true（要求 admin）才删除本地数据。

type PluginInstanceDesiredView 

type PluginInstanceDesiredView struct {
	InstanceID string            `json:"instance_id"`
	PluginID   string            `json:"plugin_id"`
	Version    string            `json:"version"`
	Enabled    bool              `json:"enabled"`
	Isolation  string            `json:"isolation"`
	Config     map[string]string `json:"config,omitempty"`
	SecretRefs []string          `json:"secret_refs,omitempty"`
	Revision   uint64            `json:"revision"`
	UpdatedAt  int64             `json:"updated_at"`
}

PluginInstanceDesiredView 是 Server 权威期望态的只读视图。 SecretRefs 只含 secret://<name> handle 名称，永不携带明文。

type PluginInstanceListResponse 

type PluginInstanceListResponse struct {
	Instances []PluginInstanceView `json:"instances"`
}

PluginInstanceListResponse 是 GET /api/plugin-instances 的载荷。

type PluginInstanceObservedView 

type PluginInstanceObservedView struct {
	State        string `json:"state"`
	Health       string `json:"health"`
	Version      string `json:"version,omitempty"`
	Detail       string `json:"detail,omitempty"`
	RestartCount int    `json:"restart_count"`
	LastHealthy  int64  `json:"last_healthy,omitempty"`
	ReportedAt   int64  `json:"reported_at,omitempty"`
}

PluginInstanceObservedView 是 Edge 上报投影的只读视图。 只有 Edge 真实上报过才存在；Server 不得凭空合成。

type PluginInstanceUpdateRequest 

type PluginInstanceUpdateRequest struct {
	Version            *string           `json:"version,omitempty"`
	Enabled            *bool             `json:"enabled,omitempty"`
	Isolation          *string           `json:"isolation,omitempty"`
	Config             map[string]string `json:"config,omitempty"`
	SecretRefs         []string          `json:"secret_refs,omitempty"`
	ConfirmPermissions bool              `json:"confirm_permissions,omitempty"`
}

PluginInstanceUpdateRequest 是 PATCH /api/plugin-instances/{id} 的载荷。 所有字段可选；只更新出现的字段。

type PluginInstanceView 

type PluginInstanceView struct {
	ID              string                      `json:"id"`
	TenantID        int64                       `json:"tenant_id"`
	EdgeID          string                      `json:"edge_id"`
	Desired         PluginInstanceDesiredView   `json:"desired"`
	HasObserved     bool                        `json:"has_observed"`
	Observed        *PluginInstanceObservedView `json:"observed,omitempty"`
	EdgeOnline      bool                        `json:"edge_online"`
	DesiredRevision uint64                      `json:"desired_revision"`
	AppliedRevision uint64                      `json:"applied_revision"`
	Drift           bool                        `json:"drift"`
	Stale           bool                        `json:"stale"`
	LastAckAt       int64                       `json:"last_ack_at,omitempty"`
}

PluginInstanceView 是 Catalog/UI 的合成视图：desired 与 observed 永远分开呈现， 绝不把「期望启用」渲染成「实际健康」。

type PluginInstanceWriteResponse 

type PluginInstanceWriteResponse struct {
	ID        string             `json:"id"`
	Revision  uint64             `json:"revision"`
	RequestID string             `json:"request_id"`
	Instance  PluginInstanceView `json:"instance"`
}

PluginInstanceWriteResponse 是所有插件实例写操作的统一响应。 Revision 是写成功后 tenant/edge 的新 desired revision；Accepted 表示 Edge 是否已 ack。

type PluginObservedInstanceData 

type PluginObservedInstanceData struct {
	InstanceID   string  `json:"instance_id"`
	PluginID     string  `json:"plugin_id"`
	Version      string  `json:"version"`
	HostOnline   bool    `json:"host_online"`
	State        string  `json:"state"`
	Health       string  `json:"health"`
	Detail       string  `json:"detail,omitempty"`
	RestartCount int     `json:"restart_count"`
	LastHealthy  int64   `json:"last_healthy,omitempty"`
	MessageRate  float64 `json:"message_rate,omitempty"`
}

PluginObservedInstanceData 是 Edge Plugin Host 的实际态。desired 字段不得放进本结构。

type PluginPermissionsData 

type PluginPermissionsData struct {
	Hardware   []string `json:"hardware,omitempty"`
	Network    []string `json:"network,omitempty"`
	Filesystem []string `json:"filesystem,omitempty"`
	Secrets    []string `json:"secrets,omitempty"`
}

PluginPermissionsData 是插件公开权限声明。这里只携带权限名称，永不携带凭据值。

type PluginStatusData 

type PluginStatusData struct {
	BootID            string                         `json:"boot_id"`
	Sequence          uint64                         `json:"sequence"`
	AppliedRevision   uint64                         `json:"applied_revision"`
	Installations     []PluginInstallationStatusData `json:"installations"`
	ObservedInstances []PluginObservedInstanceData   `json:"instances"`
}

PluginStatusData 是 Edge→Server 的全量插件实际态快照。 tenant/edge 身份必须来自已鉴权 edgeLink，禁止信任 payload 自报身份。

type PluginUIData added in v0.2.23 

type PluginUIData struct {
	APIVersion int                     `json:"apiVersion"`
	Navigation *PluginUINavigationData `json:"navigation,omitempty"`
	Pages      []PluginUIPageData      `json:"pages,omitempty"`
	Device     *PluginUIDeviceData     `json:"device,omitempty"`
}

PluginUIData is the public, declarative UI contribution attached to a Driver or Application contribution. It contains no local paths, entrypoints or secrets; custom entry values are package-relative paths.

type PluginUIDeviceData added in v0.2.23 

type PluginUIDeviceData struct {
	Sections []PluginUISectionData `json:"sections,omitempty"`
}

PluginUIDeviceData extends a Driver's device detail page.

type PluginUINavigationData added in v0.2.23 

type PluginUINavigationData struct {
	Title      string            `json:"title"`
	I18n       map[string]string `json:"i18n,omitempty"`
	Icon       string            `json:"icon,omitempty"`
	Order      int               `json:"order,omitempty"`
	Route      string            `json:"route"`
	Visibility string            `json:"visibility,omitempty"`
}

PluginUINavigationData is the stable Application navigation contribution.

type PluginUIPageData added in v0.2.23 

type PluginUIPageData struct {
	ID          string                `json:"id"`
	Title       string                `json:"title"`
	Description string                `json:"description,omitempty"`
	I18n        map[string]string     `json:"i18n,omitempty"`
	Sections    []PluginUISectionData `json:"sections"`
}

PluginUIPageData is one Application page declaration.

type PluginUISectionData added in v0.2.23 

type PluginUISectionData struct {
	Type         string            `json:"type"`
	Title        string            `json:"title,omitempty"`
	Description  string            `json:"description,omitempty"`
	EmptyText    string            `json:"emptyText,omitempty"`
	Source       string            `json:"source,omitempty"`
	RecordType   string            `json:"recordType,omitempty"`
	Presentation string            `json:"presentation,omitempty"`
	Text         string            `json:"text,omitempty"`
	Entry        string            `json:"entry,omitempty"`
	Scopes       []string          `json:"scopes,omitempty"`
	I18n         map[string]string `json:"i18n,omitempty"`
	Fields       []map[string]any  `json:"fields,omitempty"`
}

PluginUISectionData is one allowlisted Core-rendered section.

type SeriesSampleView added in v0.2.25 

type SeriesSampleView struct {
	DeviceID string  `json:"device_id"`
	Key      string  `json:"key"`
	Ts       int64   `json:"ts"`
	Value    float64 `json:"value"`
	Quality  string  `json:"quality,omitempty"`
}

SeriesSampleView 是一条数值采样历史行。Key 是通用序列键；平台不解释其设备语义。

type SeriesSamplesView added in v0.2.25 

type SeriesSamplesView struct {
	Samples    []SeriesSampleView `json:"samples"`
	NextBefore int64              `json:"next_before,omitempty"`
}

SeriesSamplesView 是 GET /api/devices/{edgeID}/{deviceID}/samples 的响应。 Samples 按时间升序；NextBefore>0 表示还有更早的数据可翻页。

type SessionView 

type SessionView struct {
	ID         string `json:"id"`
	UserID     int64  `json:"user_id"`
	CreatedAt  int64  `json:"created_at"`
	ExpiresAt  int64  `json:"expires_at"`
	LastSeenAt int64  `json:"last_seen_at"`
}

SessionView 是服务端会话视图（内部管理用，不直接透出会话 ID）。

type SnapshotData 

type SnapshotData struct {
	Devices     []DeviceView       `json:"devices"`
	Edges       []EdgeView         `json:"edges"`
	Descriptors []model.Descriptor `json:"descriptors,omitempty"`
}

SnapshotData 是浏览器连接时的全量快照。 Descriptors 随快照一并下发，给前端可靠首屏（webui store/ws.ts 宽容消费）。

type StateData 

type StateData struct {
	Online    bool           `json:"online"`
	Raw       map[string]any `json:"raw"`
	UpdatedAt int64          `json:"updated_at"` // unix 秒
	// Observations preserve entity identity and quality for Application consumers.
	// Legacy edges may omit them; Raw is never guessed into typed observations.
	Observations []EntityObservationSet `json:"observations,omitempty"`
}

StateData 是设备状态快照。Raw 为适配器自定义语义（时钟/槽位/漂移…）。

type StatsView 

type StatsView struct {
	Devices       int64 `json:"devices"`
	Events        int64 `json:"events"`
	Commands      int64 `json:"commands"`
	OldestEvent   int64 `json:"oldest_event"`
	SchemaVersion int   `json:"schema_version"`
	RetentionDays int   `json:"retention_days"`
	// AuthMode 是 server 当前**实际执行**的鉴权形态：`account`（账号模式，全部 /api/* 需凭据）、
	// `token`（仅共享 legacy 令牌：读开放、写需令牌或回环）、`open`（L0 单机：写仅接受回环来源）。
	// 取代旧的 `auth_enabled bool`——那个字段只看 legacy 令牌，账号模式下会把「必须登录」
	// 说成「未启用鉴权」。形态定义见 docs/api.md §1 不变量 1-3。
	AuthMode string `json:"auth_mode"`
}

StatsView 是存储/运行统计（系统页）。

type TenantView 

type TenantView struct {
	ID        int64  `json:"id"`
	Slug      string `json:"slug"`
	Name      string `json:"name"`
	CreatedAt int64  `json:"created_at"`
}

TenantView 是租户视图。

type TokenView 

type TokenView struct {
	ID         int64    `json:"id"`
	Name       string   `json:"name"`
	Prefix     string   `json:"prefix"`
	Scopes     []string `json:"scopes"`
	CreatedAt  int64    `json:"created_at"`
	ExpiresAt  *int64   `json:"expires_at,omitempty"`
	LastUsedAt *int64   `json:"last_used_at,omitempty"`
	RevokedAt  *int64   `json:"revoked_at,omitempty"`
}

TokenView 是租户服务令牌视图（docs/api.md §3.3）。明文只在创建响应中出现一次， 由 handler 单独拼入 `token` 字段，本结构永不携带明文。

type UserRole 

type UserRole string

UserRole 是用户角色：admin 管理、operator 可读可写、viewer 只读。 

const (
	RoleAdmin    UserRole = "admin"
	RoleOperator UserRole = "operator"
	RoleViewer   UserRole = "viewer"
)

type UserView 

type UserView struct {
	ID         int64  `json:"id"`
	Username   string `json:"username"`
	Name       string `json:"name"`
	Role       string `json:"role"`
	TenantID   int64  `json:"tenant_id"`
	TenantSlug string `json:"tenant_slug"`
	Disabled   bool   `json:"disabled,omitempty"`
}

UserView 是鉴权相关端点的用户视图（/api/auth/login、/api/auth/me、用户管理）。

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.