Grabadora Puerta de Decisión Asset Core
Docs
Documentos del Grabador

Documentación de grabación de pruebas y evidencia a prueba de manipulaciones.

Otros documentos del producto

Artefactos de configuración del tiempo de ejecución del sidecar canónico generados por recorder-contract.

Descargar: config/sidecar.md (2.3 KB) Descargar: config/sidecar.schema.json (6.2 KB) Descargar: config/sidecar.compat.json (970 B) Descargar: config/sidecar.example.toml (1.4 KB)

Configuración de tiempo de ejecución del complemento de grabadora

Resumen

Este documento se genera a partir de recorder-sidecar-config y es la referencia canónica para la semántica de configuración de tiempo de ejecución del sidecar.

Secciones de Nivel Superior

  • config_version: debe ser 1.
  • api: contiene major_version y debe ser 1.
  • recorder: identidad del grabador, selectores de esquema/hash, verificación de inicio, política de auto-sellado.
  • storage: ruta del archivo SQLite y ajuste de durabilidad/punto de control.
  • transport: modo de transporte más configuraciones unix/tcp.
  • security: controles del modo de autenticación y del archivo de token.
  • probes (opcional): comportamiento de disponibilidad/listo y política de dependencia.
  • enterprise (opcional): política de integración empresarial y configuraciones del plano de control.
  • limits: límites de cuerpo/cabecera/concurrencia/tiempo de espera.
  • ingest: encolado, micro-lotes, idempotencia y controles de flujo.
  • signer: habilitación del firmante y ruta de clave PKCS#8.
  • logging: nivel y formato del registro.

Reglas de Fallo Cerrado

  • Los campos desconocidos son rechazados en cada nivel de configuración.
  • Los archivos de configuración de Sidecar están limitados a 1 MiB.
  • hash_algorithm está fijado a sha256.
  • Non-loopback TCP requires security.mode = "token" and Non-loopback TCP requiere security.mode = "token" y require_token_for_non_loopback = true.
  • Token files must be regular files, must not be symlinks, and on Unix must Los archivos de tokens deben ser archivos regulares, no deben ser enlaces simbólicos y en Unix no deben otorgar permisos de grupo/otros.
  • Los archivos de tokens están limitados a 4096 bytes.
  • Los archivos de clave del firmante están limitados a 65536 bytes.
  • max_header_bytes no debe exceder el límite máximo 65536.
  • El modo de auto-sellado requiere campos específicos del modo (count, duration_seconds).
  • probes.enterprise_health_path must be an absolute path without control probes.enterprise_health_path debe ser una ruta absoluta sin caracteres de control.
  • probes.readiness_mode = "storage_and_enterprise" requires enterprise mode probes.readiness_mode = "storage_and_enterprise" requiere que el modo empresarial esté habilitado.

Ejemplo Canónico

Ve Docs/generated/recorder/config/sidecar.example.toml.

Artefactos Legibles por Máquina

sidecar.ejemplo.toml

config_version = 1

[api]
major_version = 1

[recorder]
recorder_id = "sidecar:production-01"
hash_algorithm = "sha256"
schema_version = 1
startup_verification_depth = 100

[recorder.auto_seal]
mode = "combined"
count = 1000
duration_seconds = 300

[storage]
path = "/var/lib/recorder/recorder.sqlite3"
sqlite_synchronous = "full"
sqlite_wal_autocheckpoint_pages = 1000
sqlite_busy_timeout_ms = 5000

[transport]
mode = "tcp"

[transport.unix]
path = "/var/run/recorder/recorder.sock"

[transport.tcp]
host = "127.0.0.1"
port = 9090
allow_non_loopback = false

[security]
mode = "token"
require_token_for_non_loopback = true
token_file = "/etc/recorder/token"

[probes]
readiness_mode = "storage_only"
enterprise_health_path = "/health"
ready_fail_on_admission_saturation = true

[enterprise]
mode = "disabled"
require_writer_lease_header = true

[limits]
max_request_body_bytes = 4194304
max_attachment_bytes = 1048576
max_concurrent_requests = 64
max_queued_requests = 128
request_timeout_seconds = 30
shutdown_drain_seconds = 10
max_header_bytes = 16384

[ingest]
queue_capacity = 8192
batch_max_commands = 256
batch_max_envelopes = 512
batch_max_bytes = 4194304
batch_max_wait_ms = 4
idempotency_ttl_seconds = 86400
idempotency_max_entries_per_stream = 10000
stream_roll_max_envelopes = 1000
stream_roll_max_duration_seconds = 300

[signer]
enabled = false
key_file = "/etc/recorder/signer.pem"

[logging]
level = "info"
format = "json"

sidecar.compat.json

{
  "api_major_version": 1,
  "baseline": {
    "hard_limits": {
      "config_file_max_bytes": 1048576,
      "max_header_bytes_hard_limit": 65536,
      "signer_key_file_max_bytes": 65536,
      "token_file_max_bytes": 4096,
      "token_min_length": 32
    },
    "optional_top_level_sections": [
      "enterprise",
      "probes"
    ],
    "required_enum_values": {
      "auto_seal_mode": [
        "none",
        "after_count",
        "after_duration",
        "combined"
      ],
      "enterprise_mode": [
        "disabled",
        "self_hosted_bootstrap",
        "managed_cloud"
      ],
      "log_format": [
        "json",
        "pretty"
      ],
      "log_level": [
        "error",
        "warn",
        "info",
        "debug",
        "trace"
      ],
      "readiness_mode": [
        "storage_only",
        "storage_and_enterprise"
      ],
      "security_mode": [
        "token",
        "open"
      ],
      "sqlite_synchronous": [
        "full",
        "normal",
        "extra"
      ],
      "transport_mode": [
        "unix",
        "tcp",
        "both"
      ]
    },
    "required_top_level_sections": [
      "config_version",
      "api",
      "recorder",
      "storage",
      "transport",
      "security",
      "limits",
      "ingest",
      "signer",
      "logging"
    ]
  },
  "compatibility_policy": {
    "breaking_changes_require_major_bump": true,
    "deprecation_overlap_days_minimum": 180,
    "v1": "pre_release_break"
  },
  "config_version": 1
}

sidecar.schema.json

{
  "$id": "https://arxiu.io/contracts/v1/config/sidecar.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "description": "Canonical sidecar runtime configuration schema.",
  "properties": {
    "api": {
      "additionalProperties": false,
      "properties": {
        "major_version": {
          "const": 1,
          "description": "Supported sidecar API major version.",
          "type": "integer"
        }
      },
      "required": [
        "major_version"
      ],
      "type": "object"
    },
    "config_version": {
      "const": 1,
      "description": "Config document version.",
      "type": "integer"
    },
    "enterprise": {
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "properties": {
              "mode": {
                "enum": [
                  "self_hosted_bootstrap",
                  "managed_cloud"
                ]
              }
            }
          },
          "then": {
            "required": [
              "control_plane_base_url",
              "control_plane_token_file"
            ]
          }
        }
      ],
      "properties": {
        "control_plane_base_url": {
          "minLength": 1,
          "type": [
            "string",
            "null"
          ]
        },
        "control_plane_token_file": {
          "minLength": 1,
          "type": [
            "string",
            "null"
          ]
        },
        "default_namespace_id": {
          "minimum": 1,
          "type": [
            "integer",
            "null"
          ]
        },
        "mode": {
          "default": "disabled",
          "enum": [
            "disabled",
            "self_hosted_bootstrap",
            "managed_cloud"
          ],
          "type": "string"
        },
        "require_writer_lease_header": {
          "default": true,
          "type": "boolean"
        }
      },
      "required": [
        "mode",
        "require_writer_lease_header"
      ],
      "type": "object"
    },
    "ingest": {
      "additionalProperties": false,
      "properties": {
        "batch_max_bytes": {
          "minimum": 1,
          "type": "integer"
        },
        "batch_max_commands": {
          "minimum": 1,
          "type": "integer"
        },
        "batch_max_envelopes": {
          "minimum": 1,
          "type": "integer"
        },
        "batch_max_wait_ms": {
          "minimum": 1,
          "type": "integer"
        },
        "idempotency_max_entries_per_stream": {
          "minimum": 1,
          "type": "integer"
        },
        "idempotency_ttl_seconds": {
          "minimum": 1,
          "type": "integer"
        },
        "queue_capacity": {
          "minimum": 1,
          "type": "integer"
        },
        "stream_roll_max_duration_seconds": {
          "minimum": 1,
          "type": "integer"
        },
        "stream_roll_max_envelopes": {
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "queue_capacity",
        "batch_max_commands",
        "batch_max_envelopes",
        "batch_max_bytes",
        "batch_max_wait_ms",
        "idempotency_ttl_seconds",
        "idempotency_max_entries_per_stream",
        "stream_roll_max_envelopes",
        "stream_roll_max_duration_seconds"
      ],
      "type": "object"
    },
    "limits": {
      "additionalProperties": false,
      "properties": {
        "max_attachment_bytes": {
          "minimum": 1,
          "type": "integer"
        },
        "max_concurrent_requests": {
          "minimum": 1,
          "type": "integer"
        },
        "max_header_bytes": {
          "maximum": 65536,
          "minimum": 1,
          "type": "integer"
        },
        "max_queued_requests": {
          "minimum": 0,
          "type": "integer"
        },
        "max_request_body_bytes": {
          "minimum": 1,
          "type": "integer"
        },
        "request_timeout_seconds": {
          "minimum": 1,
          "type": "integer"
        },
        "shutdown_drain_seconds": {
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "max_request_body_bytes",
        "max_attachment_bytes",
        "max_concurrent_requests",
        "max_queued_requests",
        "request_timeout_seconds",
        "shutdown_drain_seconds",
        "max_header_bytes"
      ],
      "type": "object"
    },
    "logging": {
      "additionalProperties": false,
      "properties": {
        "format": {
          "enum": [
            "json",
            "pretty"
          ],
          "type": "string"
        },
        "level": {
          "enum": [
            "error",
            "warn",
            "info",
            "debug",
            "trace"
          ],
          "type": "string"
        }
      },
      "required": [
        "level",
        "format"
      ],
      "type": "object"
    },
    "probes": {
      "additionalProperties": false,
      "properties": {
        "enterprise_health_path": {
          "description": "Absolute path used for enterprise dependency readiness checks.",
          "minLength": 1,
          "pattern": "^/",
          "type": "string"
        },
        "readiness_mode": {
          "default": "storage_only",
          "enum": [
            "storage_only",
            "storage_and_enterprise"
          ],
          "type": "string"
        },
        "ready_fail_on_admission_saturation": {
          "default": true,
          "type": "boolean"
        }
      },
      "required": [
        "readiness_mode",
        "enterprise_health_path",
        "ready_fail_on_admission_saturation"
      ],
      "type": "object"
    },
    "recorder": {
      "additionalProperties": false,
      "properties": {
        "auto_seal": {
          "additionalProperties": false,
          "allOf": [
            {
              "if": {
                "properties": {
                  "mode": {
                    "const": "after_count"
                  }
                }
              },
              "then": {
                "required": [
                  "count"
                ]
              }
            },
            {
              "if": {
                "properties": {
                  "mode": {
                    "const": "after_duration"
                  }
                }
              },
              "then": {
                "required": [
                  "duration_seconds"
                ]
              }
            },
            {
              "if": {
                "properties": {
                  "mode": {
                    "const": "combined"
                  }
                }
              },
              "then": {
                "required": [
                  "count",
                  "duration_seconds"
                ]
              }
            }
          ],
          "properties": {
            "count": {
              "minimum": 1,
              "type": [
                "integer",
                "null"
              ]
            },
            "duration_seconds": {
              "minimum": 1,
              "type": [
                "integer",
                "null"
              ]
            },
            "mode": {
              "enum": [
                "none",
                "after_count",
                "after_duration",
                "combined"
              ],
              "type": "string"
            }
          },
          "required": [
            "mode"
          ],
          "type": "object"
        },
        "hash_algorithm": {
          "const": "sha256",
          "description": "Supported hash algorithm.",
          "type": "string"
        },
        "recorder_id": {
          "description": "Recorder identifier.",
          "maxLength": 256,
          "minLength": 1,
          "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F]+$",
          "type": "string"
        },
        "schema_version": {
          "description": "Envelope schema version.",
          "minimum": 1,
          "type": "integer"
        },
        "startup_verification_depth": {
          "description": "Read-back verification depth at startup.",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "recorder_id",
        "hash_algorithm",
        "schema_version",
        "startup_verification_depth",
        "auto_seal"
      ],
      "type": "object"
    },
    "security": {
      "additionalProperties": false,
      "properties": {
        "mode": {
          "enum": [
            "token",
            "open"
          ],
          "type": "string"
        },
        "require_token_for_non_loopback": {
          "type": "boolean"
        },
        "token_file": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "mode",
        "require_token_for_non_loopback",
        "token_file"
      ],
      "type": "object"
    },
    "signer": {
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "key_file": {
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "enabled",
        "key_file"
      ],
      "type": "object"
    },
    "storage": {
      "additionalProperties": false,
      "properties": {
        "path": {
          "description": "SQLite store path.",
          "minLength": 1,
          "type": "string"
        },
        "sqlite_busy_timeout_ms": {
          "description": "Optional SQLite busy-timeout in milliseconds.",
          "minimum": 1,
          "type": [
            "integer",
            "null"
          ]
        },
        "sqlite_synchronous": {
          "default": "full",
          "description": "SQLite synchronous durability mode.",
          "enum": [
            "full",
            "normal",
            "extra"
          ],
          "type": "string"
        },
        "sqlite_wal_autocheckpoint_pages": {
          "default": 1000,
          "description": "WAL autocheckpoint threshold in pages.",
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "path"
      ],
      "type": "object"
    },
    "transport": {
      "additionalProperties": false,
      "properties": {
        "mode": {
          "enum": [
            "unix",
            "tcp",
            "both"
          ],
          "type": "string"
        },
        "tcp": {
          "additionalProperties": false,
          "properties": {
            "allow_non_loopback": {
              "type": "boolean"
            },
            "host": {
              "description": "IP literal host string.",
              "minLength": 1,
              "type": "string"
            },
            "port": {
              "maximum": 65535,
              "minimum": 1,
              "type": "integer"
            }
          },
          "required": [
            "host",
            "port",
            "allow_non_loopback"
          ],
          "type": "object"
        },
        "unix": {
          "additionalProperties": false,
          "properties": {
            "path": {
              "minLength": 1,
              "type": "string"
            }
          },
          "required": [
            "path"
          ],
          "type": "object"
        }
      },
      "required": [
        "mode",
        "unix",
        "tcp"
      ],
      "type": "object"
    }
  },
  "required": [
    "config_version",
    "api",
    "recorder",
    "storage",
    "transport",
    "security",
    "limits",
    "ingest",
    "signer",
    "logging"
  ],
  "title": "Recorder Sidecar Runtime Config",
  "type": "object"
}