57 lines
2.9 KiB
Markdown
57 lines
2.9 KiB
Markdown
# Templates Administrator Guide
|
|
|
|
## Permissions
|
|
|
|
- `templates:template:read` reads definitions and evidence.
|
|
- `templates:template:write` creates immutable revisions.
|
|
- `templates:template:publish` selects the revision allowed for final output.
|
|
- `templates:template:render` validates and renders supplied snapshots.
|
|
- `templates:template:admin` manages every visible tenant/group/user definition.
|
|
|
|
The managed `template_manager` role contains read, write, publish, and render.
|
|
|
|
## Scope And Publication
|
|
|
|
Definitions can be tenant-, group-, or user-scoped. Non-administrators may only
|
|
write their own user templates and templates belonging to one of their groups.
|
|
Published output remains pinned even when a later draft revision is created.
|
|
|
|
## Output Storage
|
|
|
|
Files is optional. When `files.artifact_store` is present and the actor has
|
|
`files:file:upload`, managed output is written below `Generated/Templates` with
|
|
template, input, and output hashes. Otherwise Templates stores a bounded
|
|
database payload. Review database and Files retention together before deleting
|
|
render evidence.
|
|
|
|
Without Files, output payloads are bounded and retained by Templates. Ordinary
|
|
users can list and download only output they rendered themselves; a principal
|
|
with `templates:template:admin` can inspect all tenant render evidence. Consumer
|
|
modules must not redistribute the Templates download URL directly when their
|
|
resource access rules differ.
|
|
|
|
## Operations
|
|
|
|
Apply the module Alembic migration before startup. Monitor rejected renders for
|
|
contract drift, output limits, missing Files permission, and reused idempotency
|
|
keys. HTML is designed for browser/OS printing; do not treat it as a signed PDF
|
|
or proof of physical printer delivery.
|
|
|
|
Pure rendering runs in a disposable Core worker after authorization, revision
|
|
selection and idempotency lookup. Each worker has a 15-second wall limit,
|
|
10 CPU seconds, 512 MiB address space and no file output. Typed input transport
|
|
is limited to 32 MiB and result transport to 8 MiB, including serialization
|
|
overhead; nesting is limited to 64 levels and 1,000,000 value nodes. The existing
|
|
5 MiB final output and 5,000-item limits remain. Only data DTOs cross the
|
|
boundary; principals, SQL sessions, credentials and artifact writes stay in the
|
|
parent. Completed idempotent renders return before a worker is started.
|
|
|
|
`GOVOPLAN_ISOLATED_PROCESS_CONCURRENCY` in Core controls active isolated work per
|
|
API/worker process without queuing. Busy capacity produces a sanitized retryable
|
|
render error. CPU, memory, transport or time failures stop the entire render
|
|
before artifact persistence; reduce the workload before retrying. POSIX process
|
|
resource controls are required. Missing controls, cancellation or worker failure
|
|
fails closed with no in-process fallback. Budget aggregate memory across all
|
|
slots and API/worker replicas; monitor limit and overload errors separately
|
|
from template compatibility errors.
|