@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/instrumentation/network-request.js

@@ -0,0 +1,285 @@
+import { buildLocalQuerySummary, buildLocalStructuredSummary, } from "../exporter/local-minimization.js";
+import { buildParameterSnapshotBundle, } from "../exporter/parameter-snapshot.js";
+import { allowedValuePathsFor } from "../provider/privacy-policy-store.js";
+import { toPathTemplate } from "../exporter/path-template.js";
+import { maybeParseJson, sanitizeHeaders } from "../exporter/sanitize.js";
+import { buildSchemaEvidence, deriveOutcomeClass, extractErrorCodeCandidate, extractGraphqlEvidence, } from "../exporter/schema-evidence.js";
+import { currentPageUrl, resolveUrlAgainstCurrentLocation, stripQueryFromUrl, } from "./common.js";
+const MAX_CAPTURED_RESPONSE_BODY_BYTES = 16 * 1024;
+export const headersToRecord = (headers) => {
+    if (!headers)
+        return {};
+    if (headers instanceof Headers) {
+        const record = {};
+        headers.forEach((value, key) => {
+            record[key] = value;
+        });
+        return record;
+    }
+    if (Array.isArray(headers)) {
+        const record = {};
+        for (const [key, value] of headers) {
+            record[key] = value;
+        }
+        return record;
+    }
+    const record = {};
+    for (const [key, value] of Object.entries(headers)) {
+        record[key] = String(value);
+    }
+    return record;
+};
+const normalizeBody = (body) => {
+    if (body == null)
+        return null;
+    if (typeof body === "string")
+        return maybeParseJson(body) ?? body;
+    if (body instanceof URLSearchParams) {
+        const asObject = {};
+        body.forEach((value, key) => {
+            const current = asObject[key];
+            if (Array.isArray(current)) {
+                current.push(value);
+            }
+            else if (typeof current === "string") {
+                asObject[key] = [current, value];
+            }
+            else {
+                asObject[key] = value;
+            }
+        });
+        return asObject;
+    }
+    if (typeof FormData !== "undefined" && body instanceof FormData) {
+        const asObject = {};
+        body.forEach((value, key) => {
+            const normalizedValue = typeof value === "string"
+                ? value
+                : {
+                    _type: "file",
+                    mime_type: value.type || null,
+                    size: value.size,
+                };
+            const current = asObject[key];
+            if (Array.isArray(current)) {
+                current.push(normalizedValue);
+            }
+            else if (current !== undefined) {
+                asObject[key] = [current, normalizedValue];
+            }
+            else {
+                asObject[key] = normalizedValue;
+            }
+        });
+        return asObject;
+    }
+    if (typeof Blob !== "undefined" && body instanceof Blob) {
+        return { _type: "blob", mime_type: body.type || null, size: body.size };
+    }
+    if (typeof ArrayBuffer !== "undefined" && body instanceof ArrayBuffer) {
+        return { _type: "array_buffer", byte_length: body.byteLength };
+    }
+    if (ArrayBuffer.isView(body)) {
+        return { _type: "array_buffer_view", byte_length: body.byteLength };
+    }
+    if (typeof body === "object")
+        return body;
+    return null;
+};
+export const buildParameterSource = (input) => {
+    const source = {};
+    if (input.headers && Object.keys(input.headers).length > 0) {
+        source.headers = input.headers;
+    }
+    if (input.query && Object.keys(input.query).length > 0) {
+        source.query = input.query;
+    }
+    if (input.body !== null && input.body !== undefined) {
+        source.body = input.body;
+    }
+    return source;
+};
+const readQueryValues = (rawUrl) => {
+    try {
+        const resolvedUrl = resolveUrlAgainstCurrentLocation(rawUrl);
+        if (!resolvedUrl)
+            return {};
+        const queryValues = {};
+        resolvedUrl.searchParams.forEach((value, key) => {
+            const current = queryValues[key];
+            if (current === undefined) {
+                queryValues[key] = value;
+            }
+            else if (Array.isArray(current)) {
+                queryValues[key] = [...current, value];
+            }
+            else {
+                queryValues[key] = [current, value];
+            }
+        });
+        return queryValues;
+    }
+    catch {
+        return {};
+    }
+};
+const resolveRequestShape = (rawUrl) => {
+    const resolvedUrl = resolveUrlAgainstCurrentLocation(rawUrl);
+    const path = resolvedUrl?.pathname ?? "/";
+    return {
+        path,
+        pathTemplate: toPathTemplate(path),
+        targetService: resolvedUrl?.host ?? null,
+    };
+};
+const buildRequestShapeEvidence = (input) => {
+    const requestSchemaSource = buildParameterSource({
+        query: input.queryValues,
+        body: input.normalizedRequestBody,
+    });
+    const requestSchemaEvidence = buildSchemaEvidence(Object.keys(requestSchemaSource).length > 0 ? requestSchemaSource : null);
+    const graphqlEvidence = extractGraphqlEvidence(input.normalizedRequestBody);
+    return {
+        requestKind: graphqlEvidence.requestKind ?? input.defaultRequestKind,
+        requestSchemaHash: requestSchemaEvidence.schemaHash,
+        requestFieldPaths: requestSchemaEvidence.fieldPaths,
+        requestShapeSize: requestSchemaEvidence.shapeSize,
+        graphqlOperationName: graphqlEvidence.graphqlOperationName,
+        graphqlOperationType: graphqlEvidence.graphqlOperationType,
+        graphqlTopLevelFields: graphqlEvidence.graphqlTopLevelFields,
+    };
+};
+export const buildResponseShapeEvidence = (input) => {
+    const responseSchemaEvidence = buildSchemaEvidence(input.normalizedResponseBody);
+    return {
+        outcomeClass: deriveOutcomeClass({
+            statusCode: input.statusCode,
+            failureType: input.failureType,
+            responseBody: input.normalizedResponseBody,
+        }),
+        errorCodeCandidate: extractErrorCodeCandidate(input.normalizedResponseBody),
+        responseSchemaHash: responseSchemaEvidence.schemaHash,
+        responseFieldPaths: responseSchemaEvidence.fieldPaths,
+        responseShapeSize: responseSchemaEvidence.shapeSize,
+    };
+};
+const estimateBodySizeBytes = (body) => {
+    if (body == null)
+        return undefined;
+    if (typeof body === "string")
+        return new TextEncoder().encode(body).byteLength;
+    if (typeof Blob !== "undefined" && body instanceof Blob)
+        return body.size;
+    if (typeof ArrayBuffer !== "undefined" && body instanceof ArrayBuffer) {
+        return body.byteLength;
+    }
+    if (ArrayBuffer.isView(body))
+        return body.byteLength;
+    try {
+        return new TextEncoder().encode(JSON.stringify(body)).byteLength;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const deriveFailureTypeFromStatus = (status) => {
+    if (status >= 500)
+        return "server_error";
+    if (status >= 400)
+        return "client_error";
+    return null;
+};
+export const getXhrResponseBody = (xhr) => {
+    try {
+        const contentLength = xhr.getResponseHeader("content-length");
+        if (contentLength &&
+            !Number.isNaN(Number(contentLength)) &&
+            Number(contentLength) > MAX_CAPTURED_RESPONSE_BODY_BYTES) {
+            return null;
+        }
+        if (xhr.responseType === "" || xhr.responseType === "text") {
+            if (new TextEncoder().encode(xhr.responseText).length >
+                MAX_CAPTURED_RESPONSE_BODY_BYTES) {
+                return null;
+            }
+            return maybeParseJson(xhr.responseText);
+        }
+        if (xhr.responseType === "json")
+            return xhr.response;
+        return null;
+    }
+    catch {
+        return null;
+    }
+};
+export const parseXhrHeaders = (rawHeaders) => {
+    const headers = {};
+    rawHeaders
+        .trim()
+        .split(/\r?\n/)
+        .forEach((line) => {
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex <= 0)
+            return;
+        const key = line.slice(0, separatorIndex).trim();
+        const value = line.slice(separatorIndex + 1).trim();
+        if (key)
+            headers[key] = value;
+    });
+    return headers;
+};
+export const createRequestMeta = (input) => {
+    const traceContext = input.traceContext;
+    const queryValues = readQueryValues(input.rawUrl);
+    const queryKeys = Object.keys(queryValues);
+    const querySummary = buildLocalQuerySummary(queryValues);
+    const sanitizedRequestHeaders = sanitizeHeaders(input.requestHeaders);
+    const normalizedRequestBody = normalizeBody(input.body);
+    const requestShape = resolveRequestShape(input.rawUrl);
+    // 顧客の値が入る面。**既定は全部伏せる。**顧客が画面で名指しした項目だけを
+    // `allowedPaths` が平文にする。方針がまだ届いていない間は空なので、伏せた側へ倒れる。
+    const requestParametersSnapshot = buildParameterSnapshotBundle({ query: queryValues, body: normalizedRequestBody }, {
+        allowedPaths: allowedValuePathsFor({
+            method: input.method,
+            pathTemplate: requestShape.pathTemplate,
+            direction: "request",
+        }),
+        deniedKeys: input.deniedKeys ?? [],
+    });
+    const requestShapeEvidence = buildRequestShapeEvidence({
+        queryValues,
+        normalizedRequestBody,
+        defaultRequestKind: input.defaultRequestKind,
+    });
+    const interactionId = traceContext.interactionId;
+    return {
+        method: input.method,
+        rawUrl: input.rawUrl,
+        url: stripQueryFromUrl(input.rawUrl),
+        path: requestShape.path,
+        pathTemplate: requestShape.pathTemplate,
+        targetService: requestShape.targetService,
+        startedAtMs: input.startedAtMs ?? Date.now(),
+        traceId: traceContext.traceId,
+        parentSpanId: traceContext.parentSpanId,
+        requestId: traceContext.requestId,
+        requestSpanId: traceContext.requestSpanId,
+        interactionId,
+        interactionInitiator: traceContext.interactionInitiator ??
+            (interactionId ? null : "background"),
+        interactionStartEventKind: traceContext.interactionStartEventKind ??
+            (interactionId ? null : "background_request"),
+        originFrontendInteractionId: traceContext.originFrontendInteractionId ?? null,
+        viewId: input.context.getViewId(),
+        requestHeaders: sanitizedRequestHeaders,
+        queryKeys,
+        requestParametersSnapshot,
+        requestMetadataSummary: buildLocalStructuredSummary({
+            headers: sanitizedRequestHeaders,
+            query: querySummary,
+        }) ?? {},
+        requestShapeEvidence,
+        requestSizeBytes: estimateBodySizeBytes(input.body),
+        pageUrl: currentPageUrl(),
+    };
+};

package/dist/instrumentation/network-span-attributes.d.ts

@@ -0,0 +1,25 @@
+import { type Span } from "@opentelemetry/api";
+/**
+ * 属性を書き込む側が、span に実際に求めるもの。
+ *
+ * **`Span` 全体（11 member）を求めていました。** ここで使うのは 2 つだけなので、
+ * 試験の作り物は残りを持てず `as unknown as Span` で嘘をつくしかない状態でした
+ * （`tests/README.md` §10）。3 つ目を使い始めたら、ここが変わって作り物が落ちます。
+ */
+export type AttributeWritableSpan = {
+    [K in "setAttribute" | "setStatus"]: (...args: Parameters<Span[K]>) => unknown;
+};
+import type { CaptureModuleContext } from "../provider/types.js";
+import { type HeaderRecord, type NetworkRequestMeta } from "./network-request.js";
+type ObservationContext = ReturnType<NonNullable<CaptureModuleContext["getObservationContext"]>> | null;
+export declare const setResponseSpanAttributes: (span: AttributeWritableSpan, meta: NetworkRequestMeta, input: {
+    statusCode?: number | null;
+    responseHeaders?: HeaderRecord;
+    normalizedResponseBody: unknown;
+    responseSizeBytes?: number;
+    failureType?: string | null;
+    durationMs: number;
+    observationContext: ObservationContext;
+    deniedKeys?: readonly string[];
+}) => void;
+export {};

package/dist/instrumentation/network-span-attributes.js

@@ -0,0 +1,153 @@
+import { SpanStatusCode } from "@opentelemetry/api";
+import { buildLocalStructuredSummary } from "../exporter/local-minimization.js";
+import { cluebaseAuthoredMetricAttribute, cluebaseAuthoredPropertyAttribute, } from "./cluebase-authored-attributes.js";
+import { sanitizeHeaders } from "../exporter/sanitize.js";
+import { FRONTEND_EVENT_CATEGORY, FRONTEND_EVENT_NAME, FRONTEND_EVENT_STATUS, } from "../provider/contracts.js";
+import { buildParameterSnapshotBundle } from "../exporter/parameter-snapshot.js";
+import { allowedValuePathsFor } from "../provider/privacy-policy-store.js";
+import { buildResponseShapeEvidence, } from "./network-request.js";
+const PRIVACY_POLICY_VERSION = 1;
+const setOptionalString = (span, key, value) => {
+    if (value !== null && value !== undefined && value !== "") {
+        span.setAttribute(key, value);
+    }
+};
+const setOptionalNumber = (span, key, value) => {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        span.setAttribute(key, value);
+    }
+};
+const setOptionalStringArray = (span, key, value) => {
+    if (value && value.length > 0) {
+        span.setAttribute(key, value);
+    }
+};
+const stringifyNonEmptyObject = (value) => {
+    if (Object.keys(value).length === 0)
+        return null;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return null;
+    }
+};
+const setJsonRecordAttribute = (span, key, value) => {
+    const json = stringifyNonEmptyObject(value);
+    if (json)
+        span.setAttribute(key, json);
+};
+const setRequestSpanAttributes = (span, meta, eventName, status, observationContext) => {
+    span.setAttribute("cluebase.event_category", FRONTEND_EVENT_CATEGORY.request);
+    span.setAttribute("cluebase.event_name", eventName);
+    span.setAttribute("cluebase.status", status);
+    span.setAttribute("cluebase.event_source", "frontend_sdk");
+    span.setAttribute("cluebase.occurrence.kind", "frontend_action");
+    span.setAttribute("cluebase.trace_id", meta.traceId);
+    span.setAttribute("cluebase.request.id", meta.requestId);
+    span.setAttribute("cluebase.request_span_id", meta.requestSpanId);
+    span.setAttribute("cluebase.privacy.level", "default_masked");
+    span.setAttribute("cluebase.privacy.masking_state", "masked");
+    span.setAttribute("cluebase.privacy.policy_version", PRIVACY_POLICY_VERSION);
+    span.setAttribute("http.method", meta.method);
+    span.setAttribute("http.request.method", meta.method);
+    span.setAttribute("http.route", meta.pathTemplate);
+    span.setAttribute("cluebase.path", meta.path);
+    span.setAttribute("cluebase.path_template", meta.pathTemplate);
+    setOptionalString(span, "cluebase.target_service", meta.targetService);
+    setOptionalString(span, "cluebase.parent_span_id", meta.parentSpanId);
+    setOptionalString(span, "cluebase.interaction.id", meta.interactionId);
+    setOptionalString(span, "cluebase.interaction.initiator", meta.interactionInitiator);
+    setOptionalString(span, "cluebase.interaction.start_event_kind", meta.interactionStartEventKind);
+    setOptionalString(span, "cluebase.view.id", meta.viewId);
+    setOptionalString(span, "cluebase.origin_frontend_interaction.id", meta.originFrontendInteractionId);
+    setOptionalString(span, "cluebase.page.url", meta.pageUrl);
+    setOptionalString(span, "cluebase.actor.anonymous_id", observationContext?.anonymousId);
+    setOptionalString(span, "cluebase.actor.user_id", observationContext?.userId);
+    setOptionalString(span, "cluebase.subject.organization_id", observationContext?.organizationId);
+    setOptionalString(span, "cluebase.session.id", observationContext?.sessionId);
+    setOptionalString(span, "cluebase.tab.id", observationContext?.tabId);
+    const requestEvidence = meta.requestShapeEvidence;
+    setOptionalString(span, "cluebase.request_kind", requestEvidence.requestKind);
+    setOptionalString(span, "cluebase.request_schema_hash", requestEvidence.requestSchemaHash);
+    setOptionalStringArray(span, "cluebase.request_field_paths", requestEvidence.requestFieldPaths);
+    span.setAttribute("cluebase.request_shape_size", requestEvidence.requestShapeSize);
+    span.setAttribute(cluebaseAuthoredMetricAttribute("request_shape_size"), requestEvidence.requestShapeSize);
+    setOptionalString(span, cluebaseAuthoredPropertyAttribute("request_kind"), requestEvidence.requestKind);
+    setOptionalString(span, cluebaseAuthoredPropertyAttribute("graphql_operation_name"), requestEvidence.graphqlOperationName);
+    setOptionalString(span, cluebaseAuthoredPropertyAttribute("graphql_operation_type"), requestEvidence.graphqlOperationType);
+    setOptionalStringArray(span, cluebaseAuthoredPropertyAttribute("graphql_top_level_fields"), requestEvidence.graphqlTopLevelFields);
+    setOptionalNumber(span, cluebaseAuthoredMetricAttribute("request_size_bytes"), meta.requestSizeBytes);
+    span.setAttribute(cluebaseAuthoredPropertyAttribute("request_field_paths"), meta.queryKeys);
+    // 顧客の値が入る面。**値は入れ物の中で伏せられている。**顧客が画面で名指しした
+    // 項目だけが値を持ち、その項目名は下の控えに並ぶ。
+    setJsonRecordAttribute(span, "cluebase.request_parameters_snapshot_json", meta.requestParametersSnapshot.snapshot);
+    setJsonRecordAttribute(span, "cluebase.request_metadata_json", {
+        ...meta.requestMetadataSummary,
+        path_template: meta.pathTemplate,
+        ...(meta.queryKeys.length > 0 ? { query_keys: meta.queryKeys } : {}),
+    });
+};
+export const setResponseSpanAttributes = (span, meta, input) => {
+    const responseShapeEvidence = buildResponseShapeEvidence({
+        normalizedResponseBody: input.normalizedResponseBody,
+        statusCode: input.statusCode,
+        failureType: input.failureType,
+    });
+    const eventName = input.failureType && input.statusCode == null
+        ? FRONTEND_EVENT_NAME.requestFailed
+        : FRONTEND_EVENT_NAME.requestFinished;
+    const status = eventName === FRONTEND_EVENT_NAME.requestFailed
+        ? FRONTEND_EVENT_STATUS.failed
+        : FRONTEND_EVENT_STATUS.finished;
+    setRequestSpanAttributes(span, meta, eventName, status, input.observationContext);
+    if (eventName === FRONTEND_EVENT_NAME.requestFailed) {
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: input.failureType ?? "network_error",
+        });
+    }
+    if (input.statusCode !== undefined && input.statusCode !== null) {
+        span.setAttribute("http.status_code", input.statusCode);
+        span.setAttribute("http.response.status_code", input.statusCode);
+        if (input.statusCode >= 400) {
+            span.setStatus({ code: SpanStatusCode.ERROR });
+        }
+    }
+    span.setAttribute("cluebase.duration_ms", input.durationMs);
+    setOptionalString(span, "cluebase.outcome_class", responseShapeEvidence.outcomeClass);
+    setOptionalString(span, "cluebase.error_code_candidate", responseShapeEvidence.errorCodeCandidate);
+    setOptionalString(span, "cluebase.response_schema_hash", responseShapeEvidence.responseSchemaHash);
+    setOptionalStringArray(span, "cluebase.response_field_paths", responseShapeEvidence.responseFieldPaths);
+    span.setAttribute("cluebase.response_shape_size", responseShapeEvidence.responseShapeSize);
+    span.setAttribute(cluebaseAuthoredMetricAttribute("response_shape_size"), responseShapeEvidence.responseShapeSize);
+    setOptionalNumber(span, cluebaseAuthoredMetricAttribute("response_size_bytes"), input.responseSizeBytes);
+    setOptionalString(span, cluebaseAuthoredPropertyAttribute("failure_type"), input.failureType);
+    setOptionalString(span, cluebaseAuthoredPropertyAttribute("outcome_class"), responseShapeEvidence.outcomeClass);
+    setOptionalString(span, cluebaseAuthoredPropertyAttribute("error_code_candidate"), responseShapeEvidence.errorCodeCandidate);
+    const attemptStatus = eventName === FRONTEND_EVENT_NAME.requestFailed
+        ? "failed"
+        : input.failureType
+            ? "failed"
+            : "completed";
+    span.setAttribute("cluebase.attempt_status", attemptStatus);
+    span.setAttribute(cluebaseAuthoredPropertyAttribute("request_lifecycle_outcome"), attemptStatus);
+    const sanitizedResponseHeaders = sanitizeHeaders(input.responseHeaders ?? {});
+    const responseParametersSnapshot = buildParameterSnapshotBundle({ body: input.normalizedResponseBody }, {
+        allowedPaths: allowedValuePathsFor({
+            method: meta.method,
+            pathTemplate: meta.pathTemplate,
+            direction: "response",
+        }),
+        deniedKeys: input.deniedKeys ?? [],
+    });
+    setJsonRecordAttribute(span, "cluebase.response_parameters_snapshot_json", responseParametersSnapshot.snapshot);
+    // 平文で残した項目の控え。面をまたいで 1 本にする。空なら属性を出さない。
+    setOptionalStringArray(span, "cluebase.privacy.allowed_keys", [
+        ...new Set([
+            ...meta.requestParametersSnapshot.allowedValueKeys,
+            ...responseParametersSnapshot.allowedValueKeys,
+        ]),
+    ]);
+    setJsonRecordAttribute(span, "cluebase.response_metadata_json", buildLocalStructuredSummary({ headers: sanitizedResponseHeaders }) ?? {});
+};

package/dist/instrumentation/network.d.ts

@@ -0,0 +1,16 @@
+import { type TextMapPropagator, type TracerProvider } from "@opentelemetry/api";
+import type { CaptureModuleContext, CaptureStopHandle } from "../provider/types.js";
+import { type RequestTraceContext } from "./network-request.js";
+type RequestTraceContextInput = {
+    method: string | null;
+    urlKey: string | null;
+};
+export declare const createCluebaseNetworkPropagator: () => TextMapPropagator;
+export declare const startNetworkCapture: (context: CaptureModuleContext, options?: {
+    tracerProvider?: TracerProvider;
+    deniedKeys?: readonly string[];
+    ignoreUrlPrefixes?: string[];
+    tracePropagationOrigins?: string[];
+    createRequestTraceContext?: (input?: RequestTraceContextInput) => RequestTraceContext;
+}) => CaptureStopHandle;
+export {};