Security: Add new endpoint and DLS properties

[szybia]

• add specification for new endpoint and missing properties
• how this change looks: https://github.com/user-attachments/assets/a845b7eb-77fe-4213-9715-2220af07d322

Server PRs: elastic/elasticsearch#134835 + elastic/elasticsearch#135271

[github-actions]

Following you can find the validation changes against the target branch for the APIs.

API	Status	Request	Response
indices.create	🔴	1339/1372 → 1342/1372	1372/1372
indices.put_mapping	🔴	138/145 → 139/145	148/148
security.get_stats	🟠 → 🟢	Missing type → 2/2	Missing type → 2/2

You can validate these APIs yourself by using the make validate target.

[szybia]

let me fix validate failure ^ in next PR to keep PRs scoped to one purpose, i have it passing locally

security.get_stats request has been successfully validated!
✔ 2 out of 2 test request cases are passing for security.get_stats.
✔ 2 out of 2 test response cases are passing for security.get_stats.

[pquentin]

Thank you for this!

let me fix validate failure ^ in next PR to keep PRs scoped to one purpose, i have it passing locally

I'm glad that you got make validate passing! It's not always easy. Did it require a big/unrelated change? I'd rather review something that passes the test.

[szybia]

nope change is quite small

i can put it into this PR if you prefer, i was thinking cleaner to have two PRs add new endpoint and update DLS cache stats to have new properties

change:

diff --git a/specification/xpack/usage/types.ts b/specification/xpack/usage/types.ts
index 085fff1ed..e5ad6ac55 100644
--- a/specification/xpack/usage/types.ts
+++ b/specification/xpack/usage/types.ts
@@ -320,9 +320,42 @@ export class SecurityRolesDls {
 }

 export class SecurityRolesDlsBitSetCache {
+  /** Number of entries in the cache. */
   count: integer
+  /** Human-readable amount of memory taken up by the cache. */
   memory?: ByteSize
+  /** Memory taken up by the cache in bytes. */
   memory_in_bytes: ulong
+  /**
+   * Total number of cache hits.
+   * @availability stack since=9.2.0
+   * @availability serverless
+   */
+  hits: ulong
+  /**
+   * Total number of cache misses.
+   * @availability stack since=9.2.0
+   * @availability serverless
+   */
+  misses: ulong
+  /**
+   * Total number of cache evictions.
+   * @availability stack since=9.2.0
+   * @availability serverless
+   */
+  evictions: ulong
+  /**
+   * Total combined time spent in cache for hits in milliseconds.
+   * @availability stack since=9.2.0
+   * @availability serverless
+   */
+  hits_time_in_millis: ulong
+  /**
+   * Total combined time spent in cache for misses in milliseconds.
+   * @availability stack since=9.2.0
+   * @availability serverless
+   */
+  misses_time_in_millis: ulong
 }

[pquentin]

Including this change is fine, thank you! It's quite valuable to see the green report. Plus the SecurityRolesDlsBitSetCache changes may affect other APIs, which could affect this PR too.

[pquentin]

This looks great, thank you! A few minor adjustments are needed.

[pquentin]

I realize the above uses ulong, but let's still stick to long for the new values since this is the actual Java type.

Suggested change

	hits: ulong
	hits: long

[szybia]

changed

i was thinking ulong to indicate this can't be < 0 even tho java type is long; but it all gets turned to a number i believe so probably doesn't matter

[pquentin]

Yeah, I discussed it with the team and it's... complicated. We only have 4 of those right now, and hundreds of long that are also going to be positive-only. Their handling in the different generators is unclear. It's very minor, so let's not get blocked on this.

I did revert the change to the existing ulong in 6c507dee since that would have been a breaking change.

[szybia]

just flagging in case

but when changing {hits,misses}_time_in_millis to DurationValue<UnitMillis>, it stops appearing on the bump preview ./output/openapi/elasticsearch-openapi.json

we already use this everywhere so assuming whatever we use to actually generate the docs does this correctly

• with DurationValue
• with long

[pquentin]

just flagging in case

Wow, nice catch! I alerted the docs team.

[pquentin]

Thank you for your attention to detail! LGTM.