shopdb-flask/plugins/endpoints/DELIVERY-TESTING-notes.md

Delivery testing notes (update_app + run_script)

Temporary field notes for exercising the endpoint delivery path end to end and for handing the UI work to Cameron. ASCII only, no em-dashes, no emojis, per repo style. Remove the dev test bench (view, route, nav entry) once the production delivery UI lands.

What exists today (the contract Cameron builds against)

Server allowlist (plugins/endpoints/commands.py):

• run_script - targetkind script. target is a script NAME the agent already holds in its local scriptpaths allowlist. No body or path crosses the wire.
• update_app - targetkind app. target is an appversionid that resolves to a ShopDB-hosted installer package. The server pins the package by SHA-256 and passes this version's silentargs.

Both actions require endpoints.deploy ON TOP OF endpoints.command. Queueing one is the actual authority (audited with the requesting user). The agent claims it with its collector credential.

Enqueue call (same route as every other endpoint command):

POST /api/endpoints/<assetid>/commands
{ "action": "run_script", "target": "remove-network-drives" }
{ "action": "update_app", "target": "<appversionid>" }

Rules the UI must respect:

• At most one pending/running command per endpoint. A second enqueue returns 409 (treat as "already in flight", not a failure).
• update_app is validated at enqueue: an appversionid with no installer package or unknown id is rejected 400 before it is queued.
• A version with no sha256 has no uploaded package yet. Do not offer it for update_app; the agent's integrity check will fail closed.

Read the result back:

GET /api/endpoints/<assetid>/commands

Each row carries status (pending/running/succeeded/failed), resultmessage (short summary) and resultjson (structured detail: for run_script the exit code and script path; for update_app the installer path, exit code and digest check).

Agent-facing package download (collector-authenticated, not user JWT):

GET /api/endpoints/apppackage/<appversionid>   (X-API-Key collector token)

The dev test bench

Route: /endpoints/delivery-test (sidebar "Delivery test bench", gated on endpoints.deploy). It is deliberately minimal: pick an endpoint, push a script by name or push an app version, then watch the command log pane. There is no script-library component yet, so run_script takes a free-text name; the agent runs it only if that name is in its scriptpaths.

Preparing the test endpoint

1. Copy the dev build to the test box:
   • agent\dev-bin\agent\shopdbagent.exe
   • agent\dev-bin\agent\appsettings.json Stage them the same way the site installer does (service exe + appsettings).
2. Provision the collector credential and base URL. Per repo policy these are NOT in appsettings.json; set the registry values under HKLM\SOFTWARE\GE\ShopDB (CollectorKey, BaseUrl). The shipped appsettings has baseurl empty and apikey = REPLACE_WITH_COLLECTOR_KEY so the agent fails closed until provisioned.
3. Stage the sample script where appsettings points: C:\ProgramData\ShopDB\EndpointAgent\scripts\remove-network-drives.ps1 (source: agent\dev-bin\scripts\remove-network-drives.ps1). The scriptpaths entry in appsettings.json maps the name remove-network-drives to that path.
4. For an update_app test, create the application in the Applications module, upload its installer package (this stamps the version's sha256), and note the version's appversionid.

Collecting logs

Endpoint side (the agent):

• Rolling diagnostics log: %ProgramData%\ShopDB\EndpointAgent\logs (override with logpath in appsettings). This is where run_script and update_app record what they resolved, the digest check, and the installer or script exit code.
• Windows Event Log source ShopDB Endpoint Agent for service faults.

Web UI / ShopDB side:

• The command log pane on the bench (or GET /api/endpoints/<assetid>/commands) shows status, resultmessage and resultjson reported by the agent.
• Ingest observability: unknown/unpersisted telemetry keys are logged by the endpoints plugin on the API container, so incoming agent data is visible in the app logs even before UI persistence catches up.
• Audit log records each enqueue (created EndpointCommand, action + target + asset) with the requesting user.

Notes to capture during testing (for Cameron)

• Round-trip latency from enqueue to a terminal status, at the agent cadence.
• Whether resultmessage alone is enough for the operator, or the UI needs to surface resultjson (exit codes, digest mismatches).
• How a 409 (already in flight) should read in the real UI.
• What a failed digest check or non-zero installer exit looks like end to end, so the production UI can present it clearly.