Browsing the Media Archive

About 1026 wordsAbout 3 min

The Media Archive plugin (one of the built-in apps in the operator panel) surfaces rows from media_assets as a filterable grid in the admin UI. This page is for operators and end users who consume the panel; for plugin-author docs see Plugin author guide → Admin UI.

What’s in the grid

  • Every media_assets row the caller is allowed to see (filtered by PrincipalResolver::visiblePrincipalIds() server-side).
  • Type pill (All / Images / Audio / Video / Documents) plus a search input.
  • A dashboard-style scope chip row above the search field (see Scope chips).
  • A click-through detail drawer with metadata (dimensions, duration, mime type, source URL).
  • One-click download via the existing AssetController::show() route.

Scope chips — ALL / My Media / Group X

The chip row mirrors the dashboard’s flag-chip pattern — single-select, click-the-active-chip-to-clear.

ChipWire shapeWhat it shows
Allprincipal_id[]=<every visible id>The caller’s user-principal plus every group-principal they belong to. Surfaces direct uploads + every group’s media.
My Mediaprincipal_id[]=<user-principal id>Direct uploads by the caller plus media attached to agents owned by the caller. Direct uploads surface only because the user-principal is in the list.
Group Aprincipal_id[]=<group-A principal id>Media attached to agents owned by group A. The caller’s direct uploads are intentionally excluded so a group chip never leaks user uploads.

Each chip’s label comes from GET /principals/me (which carries the type: 'user' | 'group' discriminator) plus GET /groups for friendly group names. If /principals/me resolves with the caller belonging to zero principals, the chip row hides entirely — the grid falls back to the legacy ownership union (agentOwnerUserId).

Out-of-scope ids are silently dropped

The server intersects the request values with the caller’s visiblePrincipalIds(). A typo (e.g. ?principal_id[]=abc), an id the caller doesn’t own, or an id from a different tenancy is silently dropped — the listing endpoint never surfaces filter-syntax errors so an authenticated UI never breaks on a stale id.

Empty intersection

If the caller asks for a filter that intersects with nothing they can see (e.g. asking for a foreign group after they’ve been removed from it), the controller clears the principal-id filter and the service falls back to the legacy agentOwnerUserId-based ownership union. That union is also empty when the caller is unauthenticated, so the safe default holds.

Wire shape: ?principal_id[]=…

The frontend sends the request as repeated ?principal_id[]=… keys. The array-bracket form is required — the plain repeated scalar form (?principal_id=…&principal_id=…) is collapsed to the LAST value by PHP’s parse_str, which silently dropped everything except the last group-principal when the chip row sent every visible id. The [principal_id] parameter is defined in the OpenAPI spec — see the auto-generated Media API reference.

Keyboard / a11y notes

  • Each chip is a real <button type="button"> with aria-pressed reflecting selection state.
  • Active chips are styled with bg-primary / text-primary-foreground; inactive chips use muted text.
  • The chip row is wrapped in a <fieldset> + <legend> group so assistive tech announces it as a single-select “Scope” group.

Temporary files

The grid hides temp rows by default — they crowd out the permanent grid with a stream of short-lived voice transcripts and other auto-uploaded artefacts. Three UI surfaces let operators opt back in:

  • “Include temporary files” toggle in MediaFilters. State persists in localStorage (spora.media.showTemporary.v1, default off). When off, the listing query sends ?include_temporary=false and the filter happens server-side. Flipping the toggle reloads the grid.
  • “Temporary” corner badge on MediaCard. Renders only when the toggle is on and the asset is temp; otherwise the row is filtered out before it reaches the grid.
  • “Keep file” button on MediaDetailPage for temp assets. Calls POST /api/v1/media/{id}/keep to pin the row as permanent so the per-(user, agent) retention sweep leaves it alone. Idempotent — calling on a non-temp row returns 200 without re-saving. A toast confirms the pin; the detail payload refreshes with is_temporary: false.

Keep-file auth: global admin OR the asset’s user_id == currentUserId. Non-owners receive 403; missing rows 404.

The retention sweep itself runs server-side (media:gc --temporary [--older-than-hours N], default 24 h). Per-agent retention is governed by agents.voice_message_retention_count (default 5; 0 disables auto-purge — operators must then run the GC manually or hit /keep per row). See the Media API reference for the full lifecycle: POST /api/v1/media (temp opt-in via is_temporary), GET /api/v1/media?include_temporary=true, POST /api/v1/media/{id}/keep, and the media:gc CLI.

Where the data comes from

EndpointUsed for
GET /api/v1/media?principal_id[]=…The grid itself — paginated, filtered, scoped. Returns { data: { assets, page, perPage, total, lastPage } }.
GET /api/v1/principals/meThe list of visible principals (typed: user vs group). Drives the chip row shape.
GET /api/v1/groupsFriendly group names keyed by principal_id. The chip row falls back to Group #N if this endpoint is unavailable.
GET /api/v1/media/{id}Detail drawer payload.
GET /api/v1/assets/{filename}One-click download — streams the file through AssetController::show() (token + ownership checks).
PATCH /api/v1/media/{id}Edit filename, tags, metadata, prompt, public sharing. Validators are in MediaArchiveUpdateValidator.
POST /api/v1/media/{id}/public-token/refreshRotate the public-access token for a shared asset.
POST /api/v1/media/{id}/keepPin a temp row as permanent so the retention sweep leaves it alone. Idempotent; admin-or-owner auth.