harperdb

{ "$schema": "https://json-schema.org/draft-06/schema", "$id": "https://harper.fast/schema/config-root.schema.json", "title": "HarperDB Root Configuration", "description": "JSON Schema for harperdb-config.yaml as documented in docs.html. This focuses on the primary, documented configuration sections and keys. Unknown properties are allowed for forward compatibility.", "type": "object", "properties": { "rootPath": { "type": "string", "description": "Root folder where Harper persists data, config, logs, and components. Default: user's home directory" }, "componentsRoot": { "type": "string", "description": "Path to the folder containing local component files. Default: <ROOTPATH>/components" }, "http": { "type": "object", "description": "HTTP server configuration for the main component server.", "additionalProperties": true, "properties": { "sessionAffinity": { "description": "Route multiple requests from the same client to the same thread. Use 'ip' or a header name.", "type": ["string", "null"] }, "compressionThreshold": { "type": "integer", "minimum": 0, "description": "Responses larger than this threshold (bytes) will be compressed for clients that accept compression. Default: 1200" }, "cors": { "type": "boolean", "description": "Enable Cross Origin Resource Sharing. Default: true" }, "corsAccessList": { "type": ["array", "null"], "description": "List of allowed origins for CORS.", "items": { "type": "string" } }, "corsAccessControlAllowHeaders": { "type": "string", "description": "Comma-separated list of header keys for Access-Control-Allow-Headers on OPTIONS requests. Default: 'Accept, Content-Type, Authorization'" }, "headersTimeout": { "type": "integer", "description": "Milliseconds to wait for complete HTTP headers. Default: 60000" }, "maxHeaderSize": { "type": "integer", "description": "Maximum allowed size of HTTP headers in bytes. Default: 16394" }, "requestQueueLimit": { "type": "integer", "description": "Max estimated request queue time (ms) before rejecting with 503. Default: 20000" }, "keepAliveTimeout": { "type": "integer", "description": "Keep-alive inactivity timeout in ms. Default: 30000" }, "port": { "type": "integer", "description": "HTTP port. Default: 9926" }, "securePort": { "type": ["integer", "null"], "description": "HTTPS port. Requires valid certificate + key." }, "http2": { "type": "boolean", "description": "Enable HTTP/2. Default: false" }, "timeout": { "type": "integer", "description": "Request timeout (ms). Default: 120000" }, "mtls": { "description": "Enable and configure mTLS authentication for HTTP.", "oneOf": [ { "type": "boolean" }, { "type": "object", "additionalProperties": false, "properties": { "user": { "type": ["string", "null"], "description": "Authenticate all authorized mTLS connections as this user. Default: common name from certificate or null to not auto-auth." }, "required": { "type": "boolean", "description": "Require client certificates for all HTTP connections. Default: false" }, "certificateVerification": { "description": "Enable certificate revocation checking (CRL/OCSP).", "oneOf": [ { "type": "boolean" }, { "type": "object", "additionalProperties": false, "properties": { "failureMode": { "type": "string", "enum": ["fail-open", "fail-closed"], "description": "Global behavior when verification fails. Default: 'fail-closed'" }, "crl": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Enable CRL checking. Default: true" }, "timeout": { "type": "number", "description": "Max ms to wait for CRL download. Default: 10000" }, "cacheTtl": { "type": "number", "description": "CRL cache TTL (ms). Default: 86400000" }, "gracePeriod": { "type": "number", "description": "Grace period after CRL nextUpdate (ms). Default: 86400000" }, "failureMode": { "type": "string", "enum": ["fail-open", "fail-closed"], "description": "CRL-specific failure mode. Default: 'fail-closed'" } } }, "ocsp": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Enable OCSP checking. Default: true" }, "timeout": { "type": "number", "description": "Max ms to wait for OCSP response. Default: 5000" }, "cacheTtl": { "type": "number", "description": "Cache TTL for successful OCSP (ms). Default: 3600000" }, "errorCacheTtl": { "type": "number", "description": "Cache TTL for OCSP errors (ms). Default: 300000" }, "failureMode": { "type": "string", "enum": ["fail-open", "fail-closed"], "description": "OCSP-specific failure mode. Default: 'fail-closed'" } } } } } ] } } } ] }, "logging": { "allOf": [{ "$ref": "#/definitions/loggerConfig" }], "properties": { "timing": { "type": "boolean", "description": "Log timing information for HTTP requests." }, "headers": { "type": "boolean", "description": "Log HTTP headers (verbose)." }, "id": { "type": "boolean", "description": "Assign/log unique id per request." } } } } }, "threads": { "type": "object", "description": "Harper worker thread configuration.", "additionalProperties": true, "properties": { "count": { "type": "number", "description": "Number of worker threads. Default: logical CPU count minus one" }, "debug": { "oneOf": [ { "type": "boolean" }, { "type": "object", "additionalProperties": false, "properties": { "port": { "type": "integer", "description": "Port for debugging the main thread (default 9229)" }, "startingPort": { "type": "integer", "description": "Starting port to assign unique debugging ports per thread" }, "host": { "type": "string", "description": "Debug host interface (default 127.0.0.1)" }, "waitForDebugger": { "type": "boolean", "description": "Wait for debugger before starting" } } } ] }, "maxHeapMemory": { "type": "number", "description": "Heap memory limit per thread (MB)." }, "heapSnapshotNearLimit": { "type": "boolean", "description": "Take a heap snapshot when near the heap limit." } } }, "replication": { "type": "object", "description": "Harper replication configuration for clustering and data replication.", "additionalProperties": true, "properties": { "hostname": { "type": "string", "description": "Hostname of this Harper instance." }, "url": { "type": "string", "description": "URL of this Harper instance." }, "databases": { "description": "Databases to replicate. '*' for all, array of names, or array with objects to mark sharded databases.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "sharded": { "type": "boolean" } }, "required": ["name"] } ] } } ] }, "routes": { "type": "array", "description": "Routes to connect to other nodes. Each route can be a string or an object with hostname, port, and optional startTime.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": false, "properties": { "hostname": { "type": "string" }, "port": { "type": "integer" }, "startTime": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC start time to begin replication." } }, "required": ["hostname", "port"] } ] } }, "startTime": { "type": "string", "format": "date-time", "description": "Start replication from this time." }, "revokedCertificates": { "type": "array", "items": { "type": "string" }, "description": "Array of revoked certificate serial numbers." }, "port": { "type": "integer", "description": "Replication insecure port." }, "securePort": { "type": "integer", "description": "Replication secure port. Default: 9933" }, "enableRootCAs": { "type": "boolean", "description": "Verify certificates against Node.js bundled CA store. Default: true" }, "mtls": { "type": "object", "description": "mTLS settings for replication connections (always required).", "additionalProperties": true, "properties": { "certificateVerification": { "description": "Enable certificate revocation checking (CRL/OCSP) for peer certificates.", "oneOf": [ { "type": "boolean" }, { "type": "object", "additionalProperties": false, "properties": { "failureMode": { "type": "string", "enum": ["fail-open", "fail-closed"] }, "crl": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "timeout": { "type": "number" }, "cacheTtl": { "type": "number" }, "gracePeriod": { "type": "number" }, "failureMode": { "type": "string", "enum": ["fail-open", "fail-closed"] } } }, "ocsp": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "timeout": { "type": "number" }, "cacheTtl": { "type": "number" }, "errorCacheTtl": { "type": "number" }, "failureMode": { "type": "string", "enum": ["fail-open", "fail-closed"] } } } } } ] } } }, "blobTimeout": { "type": "number", "description": "Max time (ms) to wait for blob transfer. Default: 120000" }, "failOver": { "type": "boolean", "description": "Attempt fail-over to different node when unreachable. Default: true" }, "shard": { "type": "integer", "description": "Shard id for this instance." }, "logging": { "$ref": "#/definitions/loggerConfig" } } }, "localStudio": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Enable local Harper Studio GUI. Default: false" } } }, "logging": { "type": "object", "description": "Logging configuration for Harper.", "additionalProperties": true, "properties": { "auditLog": { "type": "boolean", "description": "Enable structured table transaction logging. Default: false" }, "file": { "type": "boolean", "description": "Log to file. Default: true" }, "auditRetention": { "type": ["string", "number"], "description": "Retention of audit logs (e.g. '3d'). Default: 3d" }, "level": { "type": "string", "enum": ["trace", "debug", "info", "warn", "error", "fatal", "notify"], "description": "Verbosity of text event logs. Default: warn" }, "console": { "type": "boolean", "description": "Log console.* output to log file. Default: true" }, "root": { "type": "string", "description": "Directory where log files are written. Default: <ROOTPATH>/log" }, "path": { "type": "string", "description": "Log file path. Default: <ROOTPATH>/log/hdb.log" }, "rotation": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Enable log rotation. Default: true" }, "compress": { "type": "boolean", "description": "Compress rotated logs with gzip. Default: false" }, "interval": { "type": ["string", "null"], "description": "Time between rotations (e.g. '1D','6H','30M')." }, "maxSize": { "type": ["string", "null"], "description": "Max size before rotation (e.g. '100M', '1G')." }, "path": { "type": "string", "description": "Directory to store rotated logs. Default: <ROOTPATH>/log" } } }, "stdStreams": { "type": "boolean", "description": "Log to stdout/stderr. Default: false" }, "auditAuthEvents": { "type": "object", "additionalProperties": false, "properties": { "logFailed": { "type": "boolean", "description": "Log failed authentication events. Default: false" }, "logSuccessful": { "type": "boolean", "description": "Log successful authentication events. Default: false" } } }, "external": { "$ref": "#/definitions/loggerConfig", "description": "Logging configuration for external components that use the logger API." } } }, "authentication": { "type": "object", "description": "Default authentication settings.", "additionalProperties": true, "properties": { "authorizeLocal": { "type": "boolean", "description": "Automatically authorize requests from loopback IP as superuser. Default: true" }, "cacheTTL": { "type": "number", "description": "Milliseconds an authentication can be cached. Default: 30000" }, "enableSessions": { "type": "boolean", "description": "Enable cookie-based sessions. Default: true" }, "operationTokenTimeout": { "type": "string", "description": "Operation token expiry duration (e.g. '1d'). Default: 1d" }, "refreshTokenTimeout": { "type": "string", "description": "Refresh token expiry duration (e.g. '1d'). Default: 1d" }, "logging": { "$ref": "#/definitions/loggerConfig" } } }, "operationsApi": { "type": "object", "description": "Operations API configuration. Values default to http configuration when not provided.", "additionalProperties": true, "properties": { "network": { "type": "object", "additionalProperties": true, "properties": { "cors": { "type": "boolean" }, "corsAccessList": { "type": ["array", "null"], "items": { "type": "string" } }, "domainSocket": { "type": "string", "description": "Unix domain socket path for CLI access. Default: <ROOTPATH>/hdb/operations-server" }, "headersTimeout": { "type": "integer" }, "keepAliveTimeout": { "type": "integer" }, "port": { "type": "integer", "description": "Operations API HTTP port. Default: 9925" }, "securePort": { "type": ["integer", "null"] }, "timeout": { "type": "integer" } } }, "tls": { "$ref": "#/definitions/tlsConfig", "description": "TLS configuration overriding root TLS for Operations API" } } }, "storage": { "type": "object", "description": "Storage engine configuration.", "additionalProperties": true, "properties": { "writeAsync": { "type": "boolean", "description": "Disable fsync for faster writes (risk of data loss on crash). Default: false" }, "caching": { "type": "boolean", "description": "Enable in-memory caching of records. Default: true" }, "compression": { "oneOf": [ { "type": "boolean" }, { "type": "object", "additionalProperties": false, "properties": { "dictionary": { "type": ["string", "null"], "description": "Path to compression dictionary file." }, "threshold": { "type": "number", "description": "Only entries larger than this many bytes will be compressed." } } } ], "description": "Enable/Configure compression (LZ4). Default: true" }, "compactOnStart": { "type": "boolean", "description": "Compact non-system databases on start. Default: false" }, "compactOnStartKeepBackup": { "type": "boolean", "description": "Keep backups created by compactOnStart. Default: false" }, "maxTransactionQueueTime": { "type": "string", "description": "Max write queue time before rejecting (e.g. '45s')." }, "noReadAhead": { "type": "boolean", "description": "Advise OS to not read ahead. Default: false" }, "prefetchWrites": { "type": "boolean", "description": "Load data prior to write transactions. Default: true" }, "path": { "type": "string", "description": "Directory for all database files. Default: <rootPath>/database" }, "blobPaths": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }], "description": "Path or array of paths for blob storage. Default: <rootPath>/blobs" }, "pageSize": { "type": "number", "description": "Database page size (bytes). Default: OS default" }, "reclamation": { "type": "object", "description": "Reclamation process configuration.", "additionalProperties": true }, "logging": { "$ref": "#/definitions/loggerConfig" } } }, "tls": { "description": "TLS certificates/keys/settings for HTTPS and MQTT. Can be a single object or an array (SNI).", "oneOf": [ { "$ref": "#/definitions/tlsConfig" }, { "type": "array", "items": { "$ref": "#/definitions/tlsConfig" } } ] }, "mqtt": { "type": "object", "description": "MQTT server configuration.", "additionalProperties": true, "properties": { "port": { "type": "number", "description": "Insecure MQTT port. Default: 1883" }, "securePort": { "type": "number", "description": "Secure MQTT port. Default: 8883" }, "webSocket": { "type": "boolean", "description": "Enable MQTT over WebSockets (on http port). Default: true" }, "requireAuthentication": { "type": "boolean", "description": "Require authentication for MQTT connections. Default: true" }, "mtls": { "oneOf": [ { "type": "boolean" }, { "type": "object", "additionalProperties": false, "properties": { "user": { "type": ["string", "null"], "description": "Authenticate all authorized mTLS connections as this user (or null for none). Default: Common Name" }, "required": { "type": "boolean", "description": "Require client certificates for all MQTT connections. Default: false" }, "certificateAuthority": { "type": "string", "description": "Override CA path for MQTT. Default: tls.certificateAuthority" }, "certificateVerification": { "oneOf": [ { "type": "boolean" }, { "type": "object", "additionalProperties": false, "properties": { "timeout": { "type": "number", "description": "Max ms to wait for OCSP response. Default: 5000" }, "cacheTtl": { "type": "number", "description": "Cache TTL (ms) for verification results. Default: 3600000" }, "failureMode": { "type": "string", "enum": ["fail-open", "fail-closed"], "description": "Behavior on verification failure. Default: 'fail-open'" } } } ] } } } ] }, "logging": { "$ref": "#/definitions/loggerConfig" } } }, "databases": { "type": "object", "description": "Optional mapping of databases and tables to file system paths.", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "path": { "type": "string", "description": "Path for all files of this database." }, "auditPath": { "type": "string", "description": "Path for audit log database files for this database." }, "tables": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "path": { "type": "string", "description": "Path for this table's files." } }, "required": ["path"] } } } } }, "analytics": { "type": "object", "additionalProperties": false, "properties": { "aggregatePeriod": { "type": "number", "description": "Seconds between aggregation of raw analytics. Default: 60" }, "replicate": { "type": "boolean", "description": "Replicate aggregated analytics across cluster. Default: false" }, "logging": { "$ref": "#/definitions/loggerConfig" } } } }, "additionalProperties": true, "definitions": { "loggerConfig": { "type": "object", "additionalProperties": true, "properties": { "path": { "type": "string" }, "root": { "type": "string" }, "level": { "type": "string", "enum": ["trace", "debug", "info", "warn", "error", "fatal", "notify"] }, "tag": { "type": "string" }, "stdStreams": { "type": "boolean" } } }, "tlsConfig": { "type": "object", "additionalProperties": false, "properties": { "certificate": { "type": "string", "description": "Path to certificate file. Default: <ROOTPATH>/keys/certificate.pem" }, "certificateAuthority": { "type": "string", "description": "Path to CA file. Default: <ROOTPATH>/keys/ca.pem" }, "privateKey": { "type": "string", "description": "Path to private key file. Default: <ROOTPATH>/keys/privateKey.pem" }, "ciphers": { "type": "string", "description": "Optional explicit cipher list." }, "host": { "type": "string", "description": "Optional SNI host this certificate applies to." } } } }, "examples": [ { "rootPath": "~/hdb", "componentsRoot": "~/hdb/components", "http": { "port": 9926, "cors": true, "compressionThreshold": 1200, "mtls": { "required": false, "certificateVerification": { "failureMode": "fail-closed", "crl": { "enabled": true, "timeout": 10000, "cacheTtl": 86400000, "gracePeriod": 86400000 }, "ocsp": { "enabled": true, "timeout": 5000, "cacheTtl": 3600000, "errorCacheTtl": 300000 } } } }, "threads": { "count": 8, "maxHeapMemory": 300 }, "authentication": { "authorizeLocal": true, "enableSessions": true }, "operationsApi": { "network": { "port": 9925 } }, "logging": { "level": "warn", "file": true, "rotation": { "enabled": true, "interval": "1D", "maxSize": "100M" } }, "storage": { "path": "~/hdb/database", "blobPaths": ["~/hdb/blobs"] }, "tls": { "certificate": "~/hdb/keys/certificate.pem", "privateKey": "~/hdb/keys/privateKey.pem", "certificateAuthority": "~/hdb/keys/ca.pem" }, "mqtt": { "port": 1883, "securePort": 8883, "webSocket": true }, "analytics": { "aggregatePeriod": 60, "replicate": false }, "my-app": { "package": "git+https://github.com/example/my-app.git", "port": 4000 } } ] }