Files
0pt/src/analytics/ingestion/native-provider.ts
T

98 lines
4.1 KiB
TypeScript

/**
* src/analytics/ingestion/native-provider.ts
* ===========================================
* BI-P129, provider kind `native`: connectors 0pt implements and owns.
*
* There is nothing to integrate here — the connectors already exist and are
* already conformance-tested (`src/connectors/conformance.ts`, P061). This
* provider's whole job is to select one and report, honestly, that it is
* verified: these connectors run in this repo's CI, in-process, with no
* third-party runtime and no unreviewed dependency.
*
* The two shipped natives are deliberately heterogeneous (that was P061's
* point and it is BI-P129's DoD too — "two real source types"):
*
* http_json — remote HTTP API, opaque server-issued page token, health
* is a network round trip, record count unknown until the
* server says it is done.
* jsonl_file — local file drop, cursor is a line offset the connector
* computes itself, health is a stat(), record count exact,
* and it emits real CDC deletes.
*
* They share no code but the contract, so "both land in a canonical tier"
* is a statement about the SEAM, not about one connector.
*/
import { HttpJsonConnector, type FetchImpl } from '../../connectors/http-json-connector';
import { JsonlFileConnector } from '../../connectors/jsonl-file-connector';
import type { Connector, ValidationResult } from '../../connectors/connector';
import type {
AnalyticsConnectorProvider,
AnalyticsIngestionSpec,
ProviderExecutionPlan,
ProviderReadiness,
} from './connector-provider';
/** Native connector ids this provider can build. */
export const NATIVE_CONNECTOR_IDS = ['http_json', 'jsonl_file'] as const;
export type NativeConnectorId = (typeof NATIVE_CONNECTOR_IDS)[number];
export class NativeConnectorProvider implements AnalyticsConnectorProvider {
readonly provider = 'native' as const;
/**
* Optional injection point so a caller can supply an `HttpJsonConnector`
* with a specific `fetchImpl` (the connector's own documented test seam).
* With nothing supplied, a real connector talking to the configured URL is
* built — this is not a mock fallback.
*/
constructor(private readonly fetchImpl?: FetchImpl) {}
providerReadiness(): ProviderReadiness {
return {
provider: this.provider,
pinned_version: 'in-repo',
verified: true,
proven: [
'both native connectors pass the P061 conformance suite (tests/p0/connector-conformance.test.ts)',
'both land into a canonical analytics tier through the P062 ingestion runner ' +
'(tests/analytics/analytics-ingestion-providers.test.ts)',
'no third-party runtime and no unreviewed dependency is involved',
],
open: [
'only http_json and jsonl_file exist natively; every other source type needs dlt/Singer or a new native connector',
],
};
}
validateSpec(spec: AnalyticsIngestionSpec): ValidationResult {
const errors: string[] = [];
if (!(NATIVE_CONNECTOR_IDS as readonly string[]).includes(spec.connector_ref)) {
errors.push(
`unknown native connector "${spec.connector_ref}" (have: ${NATIVE_CONNECTOR_IDS.join(', ')})`,
);
return { valid: false, errors };
}
// Delegate the config check to the connector itself — it is the authority
// on its own config, and its `validate` is pure and never throws.
const connector = this.connectorFor(spec);
const verdict = connector.validate(spec.config);
errors.push(...verdict.errors);
return { valid: errors.length === 0, errors };
}
connectorFor(spec: AnalyticsIngestionSpec): Connector {
if (spec.connector_ref === 'http_json') {
return this.fetchImpl ? new HttpJsonConnector(this.fetchImpl) : new HttpJsonConnector();
}
if (spec.connector_ref === 'jsonl_file') return new JsonlFileConnector();
throw new Error(`unknown native connector "${spec.connector_ref}"`);
}
executionPlan(_spec: AnalyticsIngestionSpec): ProviderExecutionPlan {
return {
runtime: 'in_process',
reason: 'native connectors are Node code in this repo; they need no separate runtime and no N0D job',
};
}
}