98 lines
4.1 KiB
TypeScript
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',
|
|
};
|
|
}
|
|
}
|