Skip to content

feat(api): agent-facing config overlay route and heartbeat instance registration (11/15) #479

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gusfcarvalho merged 3 commits into from
Oct 6, 2026
Merged

feat(api): agent-facing config overlay route and heartbeat instance registration (11/15) #479

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f67642e
feat(api): agent-facing config overlay route and heartbeat instance r…
ccf-lisa[bot] Oct 5, 2026
d71ccd7
docs: heartbeats register instances under heartbeat:ingest
ccf-lisa[bot] Oct 5, 2026
64f2362
fix(api): answer a 304 config poll without loading the overlay
ccf-lisa[bot] Oct 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 92 additions & 1 deletion docs/docs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2578,9 +2578,63 @@ const docTemplate = `{
]
}
},
"/agent/config": {
"get": {
"description": "Returns the authenticated agent's current remote-configuration overlay (an RFC 7396 merge patch over its local config file, snake_case) with an opaque ETag. Send the raw ETag back as If-None-Match to get a 304 when nothing changed; never construct one. Revision 0 means no overlay. Agent JWT only; a 404 means the API predates remote configuration.",
"produces": [
"application/json"
],
"tags": [
"Agents"
],
"summary": "Get this agent's configuration overlay",
"parameters": [
{
"type": "string",
"description": "ETag of the overlay the agent already has",
"name": "If-None-Match",
"in": "header"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/handler.GenericDataResponse-agentconfig_OverlayDocument"
}
},
"304": {
"description": "Not Modified"
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/api.Error"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/api.Error"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/api.Error"
}
}
},
"security": [
{
"OAuth2Password": []
}
]
}
},
"/agent/heartbeat": {
"post": {
"description": "Creates a new heartbeat record for monitoring.",
"description": "Creates a new heartbeat record for monitoring. An authenticated agent heartbeat also refreshes the instance's last-seen time; with config_digest (new agents, mode != off) it records config_revision/config_digest and registers the instance if needed. That registration is authorized by heartbeat:ingest, not agent:sync: removing sync from an agent's role stops overlay fetches and config reports, not instance registration by heartbeats.",
"consumes": [
"application/json"
],
Expand Down Expand Up @@ -34330,6 +34384,21 @@ const docTemplate = `{
}
},
"definitions": {
"agentconfig.OverlayDocument": {
"type": "object",
"properties": {
"created-at": {
"description": "omitted for revision 0",
"type": "string"
},
"overlay": {
"type": "object"
},
"revision": {
"type": "integer"
}
}
},
"api.Error": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -36340,6 +36409,19 @@ const docTemplate = `{
"meta": {}
}
},
"handler.GenericDataResponse-agentconfig_OverlayDocument": {
"type": "object",
"properties": {
"data": {
"description": "Wrapped response data",
"allOf": [
{
"$ref": "#/definitions/agentconfig.OverlayDocument"
}
]
}
}
},
"handler.GenericDataResponse-array_handler_catalogLinkSummary": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -37850,10 +37932,19 @@ const docTemplate = `{
"uuid"
],
"properties": {
"config_digest": {
"description": "ConfigDigest is agentconfig.Digest of the effective config; sent whenever mode != off.",
"type": "string"
},
"config_revision": {
"description": "ConfigRevision is the APPLIED configuration revision, 0 when running from the file only\n(R45). Absent for old agents and mode off.",
"type": "integer"
},
"created_at": {
"type": "string"
},
"uuid": {
"description": "UUID is the agent instance id.",
"type": "string"
}
}
Expand Down
93 changes: 92 additions & 1 deletion docs/swagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2572,9 +2572,63 @@
]
}
},
"/agent/config": {
"get": {
"description": "Returns the authenticated agent's current remote-configuration overlay (an RFC 7396 merge patch over its local config file, snake_case) with an opaque ETag. Send the raw ETag back as If-None-Match to get a 304 when nothing changed; never construct one. Revision 0 means no overlay. Agent JWT only; a 404 means the API predates remote configuration.",
"produces": [
"application/json"
],
"tags": [
"Agents"
],
"summary": "Get this agent's configuration overlay",
"parameters": [
{
"type": "string",
"description": "ETag of the overlay the agent already has",
"name": "If-None-Match",
"in": "header"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/handler.GenericDataResponse-agentconfig_OverlayDocument"
}
},
"304": {
"description": "Not Modified"
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/api.Error"
}
},
"403": {
"description": "Forbidden",
"schema": {
"$ref": "#/definitions/api.Error"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/api.Error"
}
}
},
"security": [
{
"OAuth2Password": []
}
]
}
},
"/agent/heartbeat": {
"post": {
"description": "Creates a new heartbeat record for monitoring.",
"description": "Creates a new heartbeat record for monitoring. An authenticated agent heartbeat also refreshes the instance's last-seen time; with config_digest (new agents, mode != off) it records config_revision/config_digest and registers the instance if needed. That registration is authorized by heartbeat:ingest, not agent:sync: removing sync from an agent's role stops overlay fetches and config reports, not instance registration by heartbeats.",
"consumes": [
"application/json"
],
Expand Down Expand Up @@ -34324,6 +34378,21 @@
}
},
"definitions": {
"agentconfig.OverlayDocument": {
"type": "object",
"properties": {
"created-at": {
"description": "omitted for revision 0",
"type": "string"
},
"overlay": {
"type": "object"
},
"revision": {
"type": "integer"
}
}
},
"api.Error": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -36334,6 +36403,19 @@
"meta": {}
}
},
"handler.GenericDataResponse-agentconfig_OverlayDocument": {
"type": "object",
"properties": {
"data": {
"description": "Wrapped response data",
"allOf": [
{
"$ref": "#/definitions/agentconfig.OverlayDocument"
}
]
}
}
},
"handler.GenericDataResponse-array_handler_catalogLinkSummary": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -37844,10 +37926,19 @@
"uuid"
],
"properties": {
"config_digest": {
"description": "ConfigDigest is agentconfig.Digest of the effective config; sent whenever mode != off.",
"type": "string"
},
"config_revision": {
"description": "ConfigRevision is the APPLIED configuration revision, 0 when running from the file only\n(R45). Absent for old agents and mode off.",
"type": "integer"
},
"created_at": {
"type": "string"
},
"uuid": {
"description": "UUID is the agent instance id.",
"type": "string"
}
}
Expand Down
72 changes: 71 additions & 1 deletion docs/swagger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,16 @@ basePath: /api
consumes:
- application/json
definitions:
agentconfig.OverlayDocument:
properties:
created-at:
description: omitted for revision 0
type: string
overlay:
type: object
revision:
type: integer
type: object
api.Error:
properties:
errors:
Expand Down Expand Up @@ -1418,6 +1428,13 @@ definitions:
type: array
meta: {}
type: object
handler.GenericDataResponse-agentconfig_OverlayDocument:
properties:
data:
allOf:
- $ref: '#/definitions/agentconfig.OverlayDocument'
description: Wrapped response data
type: object
handler.GenericDataResponse-array_handler_catalogLinkSummary:
properties:
data:
Expand Down Expand Up @@ -2237,9 +2254,19 @@ definitions:
type: object
handler.HeartbeatCreateRequest:
properties:
config_digest:
description: ConfigDigest is agentconfig.Digest of the effective config; sent
whenever mode != off.
type: string
config_revision:
description: |-
ConfigRevision is the APPLIED configuration revision, 0 when running from the file only
(R45). Absent for old agents and mode off.
type: integer
created_at:
type: string
uuid:
description: UUID is the agent instance id.
type: string
required:
- created_at
Expand Down Expand Up @@ -14097,11 +14124,54 @@ paths:
summary: Upload an artifact
tags:
- Artifacts
/agent/config:
get:
description: Returns the authenticated agent's current remote-configuration
overlay (an RFC 7396 merge patch over its local config file, snake_case) with
an opaque ETag. Send the raw ETag back as If-None-Match to get a 304 when
nothing changed; never construct one. Revision 0 means no overlay. Agent JWT
only; a 404 means the API predates remote configuration.
parameters:
- description: ETag of the overlay the agent already has
in: header
name: If-None-Match
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/handler.GenericDataResponse-agentconfig_OverlayDocument'
"304":
description: Not Modified
"401":
description: Unauthorized
schema:
$ref: '#/definitions/api.Error'
"403":
description: Forbidden
schema:
$ref: '#/definitions/api.Error'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.Error'
security:
- OAuth2Password: []
summary: Get this agent's configuration overlay
tags:
- Agents
/agent/heartbeat:
post:
consumes:
- application/json
description: Creates a new heartbeat record for monitoring.
description: 'Creates a new heartbeat record for monitoring. An authenticated
agent heartbeat also refreshes the instance''s last-seen time; with config_digest
(new agents, mode != off) it records config_revision/config_digest and registers
the instance if needed. That registration is authorized by heartbeat:ingest,
not agent:sync: removing sync from an agent''s role stops overlay fetches
and config reports, not instance registration by heartbeats.'
parameters:
- description: Heartbeat payload
in: body
Expand Down
8 changes: 8 additions & 0 deletions internal/api/handler/agent_config_body.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
package handler

// HTTP header names used by the agent-configuration routes.
const (
headerETag = "ETag"
headerIfMatch = "If-Match"
headerIfNoneMatch = "If-None-Match"
)
Loading
Loading