fix(api): runtime settings, recorder, logs and datapath (C4)

api/discovery.yaml

@@ -227,8 +227,9 @@ paths:
                         max_bulk_close: 1000
                       flows:
                         available: true
-                        recording: on
+                        recording: on_demand
                         scopes: [ userspace_tcp, userspace_udp ]
+                        min_flows: 64
                         max_flows: 10000
                         max_steps_per_flow: 256
                         retention_seconds: 300
@@ -255,7 +256,9 @@ paths:
                       logs:
                         available: true
                         levels: [ trace, debug, info, warn, error ]
+                        filters: [ level, target ]
                         retention_seconds: 60
+                        min_buffered_records: 64
                         max_buffered_records: 4096
                       dns_query:
                         available: true
@@ -275,6 +278,7 @@ paths:
                         entry_kinds: [ positive, negative ]
                       dns_log:
                         available: true
+                        min_records: 64
                         max_records: 2048
                         max_page_size: 500
                       dns_rules:
@@ -809,21 +813,28 @@ schemas:
                 type: boolean
               recording:
                 type: string
-                enum: [ off, on, sampled ]
+                enum: [ off, on, sampled, on_demand ]
+                description: The engine's flow recording policy, not whether the recorder is capturing now. off records none, because the configuration does not permit the flow recorder or its mode is off; on records every flow in scopes (mode on); sampled records a subset; on_demand is mode auto, recording while clients create demand, whether or not any client does now. recording.flows.active in GET /runtime/settings reports whether the recorder is capturing.
               scopes:
                 type: array
                 uniqueItems: true
                 items:
                   $ref: ./openapi.yaml#/components/schemas/FlowScope
+              min_flows:
+                $ref: ./openapi.yaml#/components/schemas/SafeUInt
+                minimum: 1
+                description: Smallest flows.max_flows a runtime-settings PATCH may set. Absent means 1.
               max_flows:
                 type: integer
                 minimum: 1
+                description: The largest flow capacity the engine supports, which is the most a runtime-settings PATCH may set, not the current value. The current value is flows.max_flows in GET /runtime/settings.
               max_steps_per_flow:
                 type: integer
                 minimum: 1
               retention_seconds:
                 type: integer
-                minimum: 0
+                minimum: 1
+                description: The longest terminal-flow retention the engine supports, which is the most a runtime-settings PATCH may set, not the current value. The smallest a PATCH may set is always 1. The current value is flows.retention_seconds in GET /runtime/settings.
               snapshot_ttl_seconds:
                 type: integer
                 minimum: 1
@@ -918,7 +929,7 @@ schemas:
                 available:
                   const: true
             then:
-              required: [ levels, retention_seconds, max_buffered_records ]
+              required: [ levels, filters, retention_seconds, max_buffered_records ]
             properties:
               available:
                 type: boolean
@@ -928,10 +939,23 @@ schemas:
                 uniqueItems: true
                 items:
                   $ref: ./openapi.yaml#/components/schemas/LogLevel
+              filters:
+                type: array
+                uniqueItems: true
+                description: The GET /logs query filters this engine applies. level is always listed; a filter not listed returns 422 unsupported_value.
+                items:
+                  type: string
+                  enum: [ level, target ]
+                contains:
+                  const: level
               retention_seconds:
                 type: integer
                 minimum: 1
                 description: Maximum age of a replayable record, in seconds. A resume cursor older than this returns 409 event_cursor_expired even when the ring has room.
+              min_buffered_records:
+                $ref: ./openapi.yaml#/components/schemas/SafeUInt
+                minimum: 1
+                description: Smallest log.buffered_records a runtime-settings PATCH may set. Absent means 1.
               max_buffered_records:
                 $ref: ./openapi.yaml#/components/schemas/SafeUInt
                 minimum: 1
@@ -993,6 +1017,10 @@ schemas:
             properties:
               available:
                 type: boolean
+              min_records:
+                $ref: ./openapi.yaml#/components/schemas/SafeUInt
+                minimum: 1
+                description: Smallest dns_log.max_records a runtime-settings PATCH may set. Absent means 1.
               max_records:
                 $ref: ./openapi.yaml#/components/schemas/SafeUInt
                 minimum: 1

api/dns.yaml

@@ -796,8 +796,10 @@ schemas:
       entries:
         $ref: ./openapi.yaml#/components/schemas/UInt64
       entry_capacity:
-        $ref: ./openapi.yaml#/components/schemas/UInt64
-        description: Effective entry limit after the engine applies its bounds, at most 100,000.
+        oneOf:
+          - $ref: ./openapi.yaml#/components/schemas/UInt64
+          - type: "null"
+        description: Effective entry limit after the engine applies its bounds, or null when the cache has no entry limit or the engine cannot report it.
   DnsLogRecord:
     type: object
     required: [ id, observed_at, src, question, status, cached, upstream, route, elapsed_ms, answers ]

api/flow-steps.yaml

@@ -211,7 +211,9 @@ schemas:
         enum: [ kernel, userspace ]
       action:
         type: string
-        enum: [ pass, redirect, hold, arm_direct, activate_direct, activate_proxy, drop ]
+        pattern: ^[a-z][a-z0-9_]*$
+        maxLength: 64
+        description: pass lets the packet continue without the proxy, redirect hands it to the userspace proxy, hold keeps it until a pending decision completes, and drop discards it. Any other value is an engine-defined step documented with that engine; clients show an unknown value as it is.
       reason:
         type: string
         minLength: 1
@@ -372,7 +374,7 @@ schemas:
       mode_override:
         type: string
         enum: [ none, direct, global, unknown ]
-        description: Clash-mode override observed for this outbound attempt, separate from the configured dial mode. This field does not expose a native runtime-mode setting. none means no override was applied; unknown means the recorder could not determine it.
+        description: Engine mode override observed for this outbound attempt, separate from the configured dial mode. This field does not expose a native runtime-mode setting. none means no override was applied; unknown means the recorder could not determine it.
       selection_path:
         type: array
         items:

api/logs.yaml

@@ -35,7 +35,7 @@ paths:
           example: info
         - name: target
           in: query
-          description: Case-sensitive literal module prefix; omit for all targets.
+          description: Case-sensitive literal prefix of LogRecord.target; omit for all targets. Requires target in resources.logs.filters, otherwise 422 unsupported_value. Records whose target is null never match.
           schema:
             type: string
             minLength: 1
@@ -85,6 +85,29 @@ paths:
           $ref: ./openapi.yaml#/components/responses/EventCursorExpired
         "413":
           $ref: ./openapi.yaml#/components/responses/TooLarge
+        "422":
+          description: level is a LogLevel member not in resources.logs.levels, or target is set while resources.logs.filters omits target (unsupported_value).
+          headers:
+            Cache-Control:
+              $ref: ./openapi.yaml#/components/headers/NoStore
+            X-Content-Type-Options:
+              $ref: ./openapi.yaml#/components/headers/NoSniff
+          content:
+            application/json:
+              schema:
+                $ref: ./openapi.yaml#/components/schemas/ErrorResponse
+              examples:
+                unadvertised_filter:
+                  value:
+                    error:
+                      code: unsupported_value
+                      message: target is not an advertised log filter.
+                      details: null
+                    request_id: request-5
+                  x-headers:
+                    Content-Type: application/json
+                    Cache-Control: no-store
+                    X-Content-Type-Options: nosniff
         "429":
           $ref: ./openapi.yaml#/components/responses/RateLimited
         "503":
@@ -102,9 +125,9 @@ schemas:
       level:
         $ref: ./openapi.yaml#/components/schemas/LogLevel
       target:
-        type: string
+        type: [ string, "null" ]
         minLength: 1
-        description: Engine module name, not a network destination.
+        description: The engine component that emitted the record, such as a module name; not a network destination. null when the engine does not report one.
       message:
         type: string
         minLength: 1

api/runtime.yaml

@@ -458,9 +458,18 @@ paths:
                         epoch: "3"
                       attachments:
                         - name: wan_ingress
+                          kind: interface
                           interface: eth0
                           direction: ingress
                           state: attached
+                        - name: connect4
+                          kind: cgroup
+                          cgroup: /
+                          state: attached
+                        - name: sk_msg_verdict
+                          kind: other
+                          hook: sk_msg verdict on the socket map
+                          state: attached
                       maps:
                         state: ready
                         conn_state:
@@ -868,26 +877,70 @@ schemas:
         properties:
           attachments:
             type: array
+            description: The attachments the engine checks. The list may be partial; an engine need not report every program it attached.
             items:
               $ref: ./openapi.yaml#/components/schemas/EbpfAttachment
           maps:
             $ref: ./openapi.yaml#/components/schemas/EbpfMaps
   EbpfAttachment:
     type: object
-    required: [ name, interface, direction, state ]
+    required: [ name, kind, state ]
+    description: One program attachment. An interface attachment names the interface and direction, a cgroup attachment names the cgroup, and any other attachment, such as a sockmap verdict or a tracing program, describes its hook in `hook`.
     properties:
       name:
         type: string
         minLength: 1
+        description: Program or hook name.
+      kind:
+        type: string
+        enum: [ interface, cgroup, other ]
       interface:
         type: string
         minLength: 1
       direction:
         type: string
         enum: [ ingress, egress ]
+      cgroup:
+        type: string
+        minLength: 1
+        description: cgroup v2 path relative to the cgroup2 mount; / is the root cgroup.
+      hook:
+        type: string
+        minLength: 1
+        description: Where an `other` attachment is attached, in the engine's words, such as the sockmap a verdict program serves or the kernel function a tracing program hooks.
       state:
         type: string
         enum: [ attached, detached, error, unknown ]
+    allOf:
+      - if:
+          properties:
+            kind:
+              const: interface
+        then:
+          required: [ interface, direction ]
+          properties:
+            cgroup: false
+            hook: false
+      - if:
+          properties:
+            kind:
+              const: cgroup
+        then:
+          required: [ cgroup ]
+          properties:
+            interface: false
+            direction: false
+            hook: false
+      - if:
+          properties:
+            kind:
+              const: other
+        then:
+          required: [ hook ]
+          properties:
+            interface: false
+            direction: false
+            cgroup: false
   EbpfMaps:
     type: object
     required: [ state, conn_state ]