ror-internals

name

ror-internals

description

ReadonlyREST internal architecture knowledge — kibana rule semantics and decision tree (BaseKibanaRule.shouldMatch, shared by the kibana and legacy kibana_access rules), FLS engine strategies, correlation-ID header contract, ROR admin API endpoints and their ES action names. Use when coding or reviewing changes to the kibana rules, FLS/fields rule, audit logging, or the _readonlyrest admin/metadata APIs.

ROR Internals (ES plugin)

Distilled from beshu-tech/readonlyrest-internal/architecture/ and api/. Treat as design intent; the code is authority (update this on discrepancy).

kibana rule

Shared decision tree (shouldMatch): core/.../blocks/rules/kibana/BaseKibanaRule.scala. Two concrete rules extend it:

• Current: KibanaUserDataRule.scala — YAML name kibana.
• Legacy: KibanaAccessRule.scala — YAML name kibana_access, @deprecated since 1.48.0.

Action groups are Scala PatternsMatcher vals in KibanaActionMatchers.scala (roActionPatternsMatcher, rwActionPatternsMatcher, clusterActionPatternsMatcher, adminActionPatternsMatcher, nonStrictActions, indicesWriteAction) — there is no Constants.java.

• Omitting kibana_access ≡ unrestricted. The explicit unrestricted value exists so YAML anchor/template blocks can override a templated rw default.
• Design intent of all restricted levels: the kibana index is writable (saved objects must work), all other "data indices" are read-only — protect against accidental data loss. Special-case writable indices exist (e.g. reporting).
• admin grants rw-level kibana access plus the full adminActionPatternsMatcher set on no-index requests and the ROR config index / index-management / tags paths (step 9) — that includes indices:admin/create, indices:admin/ilm/*, cluster:admin/ingest/pipeline/put, etc., none of which rw can reach. It also gates the ROR settings/activation-keys APIs.

level	kibana_index	data indices	reporting index	cluster mgmt	ROR settings API
admin	full	read only	full	read only	full
rw	full	read only	full	read only	none
ro	non-strict only¹	read only	full	none	none
ro_strict	read only	read only	none	none	none
api_only²	non-strict only²	read only	none	none	none

¹ ro cannot modify the kibana index in general (kibanaCanBeModified = false). It only permits a narrow allow-list of saved-object writes via isRoNonStrictCase (step 8) — discover UI state, short URLs, index-pattern/url/config doc updates. It is not full kibana-index write access.

² api_only (YAML value api_only) is its own KibanaAccess value, not an alias. On the kibana index it behaves like ro, not ro_strict: kibanaCanBeModified is false for RO | ROStrict | ApiOnly, but step 8 (isRoNonStrictCase) is gated by isAccessOtherThanRoStrictConfigured (access =!= ROStrict) — true for api_only, so it CAN reach the narrow non-strict kibana-write allow-branch (discover state / short URLs), which ro_strict never can. Its distinct restriction is the allowed_api_paths coupling (KibanaUserDataRuleDecoder.scala), a separate layer gating which ROR/ES API paths may be called.

Decision tree — shouldMatch is a short-circuit OR chain (first match → ALLOW; if none match → REJECT). Order below mirrors BaseKibanaRule.shouldMatch exactly:

1. isUnrestrictedAccessConfigured — access level is unrestricted.
2. isUserMetadataRequest — ROR user-metadata path (login).
3. isDevNullKibanaRelated — request targets the internal .kibana-devnull index.
4. isRoAction — action matches roActionPatternsMatcher.
5. isClusterAction — action matches clusterActionPatternsMatcher.
6. emptyIndicesMatch — request has no indices AND ((kibana writable AND RW action) OR (admin access AND admin action)). Not a blanket allow.
7. isKibanaSimpleData — kibana writable AND request is a Kibana sample-data index/stream.
8. isRoNonStrictCase — targets kibana index, level ≠ ro_strict, kibana not modifiable, non-strict allowed path AND non-strict action (saves discover UI state / short URLs).
9. isAdminAccessEligible — admin access configured AND admin action AND request allowed for admin (no-index, ROR index, index-management or tags path).
10. isKibanaIndexRequest — kibana writable AND targeting kibana index AND (RO OR RW OR indices:data/write/* action).

Changing the order of these checks is a behavioral change — review accordingly.

Note: indices:data/write/* is not blanket-rejected — it's allowed via step 10 (writable kibana index) and is also a member of adminActionPatternsMatcher (step 9).

FLS (fields rule) engines

Code: FieldsFiltering.scala — per ES-version module, e.g. es94x/src/main/scala/tech/beshu/ror/es/handler/response/FieldsFiltering.scala (NOT core/; uses XContentMapValues.filter, same method as ES source filtering). The strategy types (FlsAtLuceneLevelApproach, BasedOnBlockContextOnly, RequestFieldsUsage) live in core/.../domain/elasticsearch.scala; strategy resolution is in the fields rule.

• Engines: es_with_lucene (default — ES handles, lucene fallback), es (no fallback), and a hidden, undocumented lucene engine: full old-style lucene handling, kept as an emergency escape hatch when the ES-level path has a bug. Never remove it; never document it publicly.
• Request field usage trifurcation (RequestFieldsUsage): NotUsingFields (best case), UsingFields (extractable → not-allowed fields get obfuscated, e.g. field1 → field1_ROR_12Xb593a24), CannotExtractFields (query_string, function_score, wildcards, scripts — no way to enumerate fields → must fall back to lucene).
• Resolved strategies: FlsAtLuceneLevelApproach (thread-context header set per ES module), BasedOnBlockContextOnly.EverythingAllowed, BasedOnBlockContextOnly.NotAllowedFieldsUsed (query rewrite via QueryWithModifiableFields in each ES module). The resolved strategy is logged under fls.
• Lucene-level FLS requires ROR on all nodes and is slow; ES-level does not. Keep this constraint in mind when reviewing FLS changes.

Correlation ID contract

ROR ES is session-unaware; the x-ror-correlation-id request header (http.scala) correlates requests. If absent, ROR generates one as a bare UUID (CorrelationId.random, http.scala). The metadata endpoint (/_readonlyrest/metadata/user) echoes that CorrelationId back as the correlation_id JSON body field (MetadataResponse.scala), NOT as a response header — there is no x-ror-logging-id. Don't confuse it with RequestContext.Id (RequestContext.scala), the separate internal per-request id of the form <correlationId>-<hashCode>#<taskId> used in log output — that composite is NOT what the metadata endpoint returns. The ID goes into the audit log; Kibana relies on this contract for session-scoped log correlation.

ROR API endpoints ↔ ES actions

Every ROR REST endpoint maps to a dedicated ES action name (used in ACL actions rule and audit). The canonical names below are cluster:internal_ror/* — that is what RorAction declares (elasticsearch.scala) and what audit logs emit. The older cluster:ror/* spellings are legacy aliases still accepted in ACL YAML for backward compat (via rorActionByOutdatedName) but never appear in audit output — don't grep audit logs for them. Keep the mapping stable:

Endpoint	Action (canonical; cluster:ror/* legacy alias)
GET /_readonlyrest/metadata/user	cluster:internal_ror/user_metadata/get
POST /_readonlyrest/admin/refreshconfig	cluster:internal_ror/config/refreshsettings
GET/POST /_readonlyrest/admin/config (+ /config/file, /config/audit)	cluster:internal_ror/config/manage (all served by MainSettingsApi)
POST/DELETE /_readonlyrest/admin/config/test	cluster:internal_ror/testconfig/manage; in-memory test config, TTL via the ttl field in the POST request body (TestSettingsApi)
POST/DELETE /_readonlyrest/admin/config/test/authmock	cluster:internal_ror/authmock/manage; mocks persist until DELETE or plugin restart (no TTL in the current AuthMockApi)
POST /_readonlyrest/admin/audit/event	cluster:internal_ror/audit_event/put

Behavioral invariants:

• Audit event API: body ≤ 5,000 bytes (MAX_AUDIT_EVENT_REQUEST_CONTENT_IN_BYTES = 5 * 1000, not 5,120 — 413 otherwise); request is always audited, but custom fields are added only if the request is ALLOWED; custom fields must never overwrite default serializer fields.
• Auth mocks exist to support impersonation (IMPERSONATE_AS header) for rules backed by external services (LDAP, external authn/authz) — ROR can't query the real service with the impersonated user's credentials, so it answers from the mock. Mocks persist until an explicit DELETE or a plugin restart — there is no server-side TTL in the current AuthMockApi (unlike the test config endpoint, which does take a ttl).
• Cluster config summary (cluster:internal_ror/config/manage): the handling node propagates to all nodes and compares each response against its own config; any difference is a warning (NODE_RETURNED_CONFIG_ERROR, NODE_FORCED_FILE_CONFIG, ...); an error loading the current node's config fails the whole request (nothing to compare against).
• 403 body shape for all endpoints is the standard ROR forbidden JSON ("reason":"forbidden"); don't invent new error shapes.