SplunkStore — Splunk log ingestion & search

SplunkStore — Splunk log ingestion & search Overview Splunk is a log-ingestion and search platform. Data is ingested through the HTTP Event Collector (HEC) and searched with SPL (Search Processing Language) via the REST search API. There is no SQL-shaped query surface, no row-level UPDATE/DELETE, and no identifier escaping, so Splunk does not fit the SQL Dialect interface (src/dialects/dialect.ts). SplunkStore therefore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes Splunk's HEC ingest and REST search API (SPL search jobs plus index/sourcetype metadata) directly. Identity: Property | Value | --------- | ----------- | name | 'splunk' | library | 'fetch' | Driver: splunk-sdk if present, else HTTP over fetch The ingest/search methods always speak the REST/HEC HTTP API over the global fetch (so library is 'fetch'). Separately, if the optional splunk-sdk package happens to be installed, it is lazily require()d at connect() time and surfaced via getSdk() (returning null when not installed). The SDK is not loaded when a client is injected. When no client is injected, an internal client over fetch + baseURL is built at connect time by createFetchClient(baseURL, headers). Injected client SplunkStoreOptions accepts a pre-built client implementing the SplunkHttpClient interface. When provided it is used verbatim and baseURL is ignored — this is how the test suite injects a mock (no network, no SDK). Connection Option | Type | Purpose | --------- | ------------------------ | ----------------------------------------------------------------------------- | baseURL | string | Base URL of the Splunk HEC/REST endpoint. Defaults to https://localhost:8088. | token | string | HEC token, merged into headers as Authorization: Splunk <token>. | client | SplunkHttpClient | Pre-built HTTP client. When set, baseURL is ignored. | headers | Record<string, string> | Extra HTTP headers sent with every internal-client request. | Injected-client form Methods Metadata reads route through an internal doGet, which wraps any client failure in a DatabaseError. Calling a method before connect() (or after disconnect()) throws a ConnectionError. Lifecycle Method | Signature | Behavior | ------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client if provided, otherwise builds a fetch client and lazily requires splunk-sdk. Idempotent. | disconnect | disconnect(): Promise<void> | Clears the client, SDK reference, and connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): SplunkHttpClient | Returns the underlying (internal or injected) client. Throws ConnectionError if not connected. | getSdk | getSdk(): any | Returns the lazily-required splunk-sdk module, or null if not installed. | Ingest / search / metadata Method | Signature | Endpoint | Behavior | --------- | ------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------- | push | push(meta: SplunkEventMeta, events: unknown[]): Promise<any> | POST /services/collector/event | Sends a batch of events to the HEC. Each event is wrapped in a HEC envelope carrying the shared meta; envelopes are newline-concatenated. | query | query(spl: string, options?: SplunkSearchOptions): Promise<any> | POST /services/search/jobs | Dispatches an SPL search (form-urlencoded). The search string is prefixed with search unless it already begins with search/\|. Returns the parsed response (job SID, or oneshot results). | labels | labels(): Promise<any> | GET /services/data/sourcetypes | Lists the configured source types (outputmode=json). | streams | streams(): Promise<any> | GET /services/data/indexes | Lists the configured indexes. | Option / meta shapes Example Verification status Unit / mock-verified only. The tests in tests/nosql/splunk.test.ts are fully mock-driven: an in-memory SplunkHttpClient that records every request and returns canned responses is injected via SplunkStoreOptions.client. There is no live Splunk server and no network, and the optional splunk-sdk package is not installed. What this proves: push posts newline-delimited HEC envelopes to /services/collector/event with the shared meta merged into each. query posts form-urlencoded to /services/search/jobs, prefixing search and setting outputmode/earliesttime, and does not double-prefix a generating search. labels/streams route to the sourcetypes/indexes endpoints. Lifecycle: idempotent connect(), getClient() returning the injected client, getSdk() staying null when a client is injected, and ConnectionError before connect(). Error handling: client failures wrapped in DatabaseError. What this does not prove: live execution against a real Splunk deployment, nor any code path through the actual splunk-sdk. Request/response shapes are verified against Splunk's documented HEC/REST contract, but end-to-end execution over the wire has not been exercised here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories