dulvac opened a new pull request, #3058:
URL: https://github.com/apache/jackrabbit-oak/pull/3058
Documentation for the audit SPI added under OAK-12331.
Two new pages under `oak-doc/src/site/markdown/security/`:
- **`audit.md`** — consumer guide: the event model, the two producer paths
(commit-attached and fire-and-forget), the `commit.*` metadata keys, how to
configure and probe the pipeline, how to emit events and implement a
listener, and the trust model.
- **`audit-design.md`** — design document: pipeline internals, the SPI layout
across `oak-core-spi` / `oak-security-spi` / `oak-core`, OSGi and embedded
wiring, and the threading and ordering rules the implementation relies on.
Both are linked from `security/overview.md` and nested under Security in
`site.xml`. Three diagrams ship as PNGs, matching the convention used
elsewhere in oak-doc; the mermaid sources are in this branch's history.
### Notes for reviewers
The pages are written as reference documentation for the SPI rather than as a
proposal, so they describe the implementation in the present tense. The
implementation itself is a separate change; **this PR is docs only and should
not be merged ahead of it**, or the site will describe an SPI that is not in
the release.
Points that took verification against the implementation, in case they are
worth a second look:
- The observer drains the per-session buffer *before* checking the feature
toggle. That is deliberate — draining unconditionally is what stops a
mid-flight toggle flip from stranding staged events for a later commit to
misattribute.
- The threading invariant is that observers are notified on the merge thread
before `merge` returns, not that every store routes through
`ChangeDispatcher`. `MemoryNodeStore` iterates its observers directly from
`setRoot`.
- Two segment configurations silently produce no commit-attached events: a
cold-standby instance, and a store configured through
`SegmentNodeStoreFactory` without `dispatchChanges` set. Both are called
out.
- The per-session buffer cap means a persisted write can leave no audit event
behind. Documented as a gap in the trail, since it matters for anyone
building a compliance record.
- The embedded wiring snippet has been compiled and run; it delivers events
with the `commit.*` decoration present.
`mvn site -Pdoc` builds clean and the RAT check passes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
