You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flagon.apache.org by au...@apache.org on 2026/10/11 15:14:01 UTC
(flagon) branch master updated: feat(userale): add pluggable LogExporter architecture, unified headers, and ProtoJsonExporter (#133, #139, #142, #143) (#184)
This is an automated email from the ASF dual-hosted git repository.
brucearctor pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flagon.git
The following commit(s) were added to refs/heads/master by this push:
new 1b8c34a feat(userale): add pluggable LogExporter architecture, unified headers, and ProtoJsonExporter (#133, #139, #142, #143) (#184)
1b8c34a is described below
commit 1b8c34a51328ce0c6984dd5f5a01a2f327be22c8
Author: brucearctor <50...@users.noreply.github.com>
AuthorDate: Sun Oct 11 08:13:56 2026 -0700
feat(userale): add pluggable LogExporter architecture, unified headers, and ProtoJsonExporter (#133, #139, #142, #143) (#184)
---
.../packages/flagon-userale/src/configure.ts | 2 +
.../flagon-userale/src/exporters/headers.ts | 54 ++++
.../flagon-userale/src/exporters/http-json.ts | 126 ++++++++
.../packages/flagon-userale/src/exporters/index.ts | 71 +++++
.../flagon-userale/src/exporters/proto-json.ts | 219 +++++++++++++
.../packages/flagon-userale/src/exporters/types.ts | 40 +++
.../flagon-userale/src/exporters/websocket.ts | 48 +++
.../flagon-userale/src/getInitialSettings.ts | 7 +
.../userale/packages/flagon-userale/src/main.ts | 15 +
.../packages/flagon-userale/src/sendLogs.ts | 155 +++------
.../userale/packages/flagon-userale/src/types.d.ts | 14 +-
.../flagon-userale/test/spec/exporters.spec.ts | 349 +++++++++++++++++++++
.../flagon-userale/test/spec/sendLogs.spec.ts | 41 ++-
13 files changed, 1034 insertions(+), 107 deletions(-)
diff --git a/products/userale/packages/flagon-userale/src/configure.ts b/products/userale/packages/flagon-userale/src/configure.ts
index 6e42776..0261521 100644
--- a/products/userale/packages/flagon-userale/src/configure.ts
+++ b/products/userale/packages/flagon-userale/src/configure.ts
@@ -30,6 +30,8 @@ export class Configuration {
public authHeader: Settings.AuthHeader = null;
public browserSessionId: Settings.SessionId = null;
public custIndex: Settings.CustomIndex = null;
+ public exporter: Settings.CustomExporter = null;
+ public exporterType: Settings.ExporterType = "http-json";
public headers: Settings.Headers = null;
public httpSessionId: Settings.SessionId = null;
public logCountThreshold: number = 0;
diff --git a/products/userale/packages/flagon-userale/src/exporters/headers.ts b/products/userale/packages/flagon-userale/src/exporters/headers.ts
new file mode 100644
index 0000000..a1443b2
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/headers.ts
@@ -0,0 +1,54 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Configuration } from "@/configure";
+import { updateAuthHeader, updateCustomHeaders } from "@/utils";
+
+/**
+ * Builds the HTTP headers for outgoing log requests, unifying
+ * Authorization (static or callback), x-api-key, and custom headers.
+ * @param {Configuration} config Configuration singleton.
+ * @return {Headers} Constructed Fetch Headers instance.
+ */
+export function buildHeaders(config: Configuration): Headers {
+ const headers = new Headers({
+ "Content-Type": "application/json;charset=UTF-8",
+ });
+
+ updateAuthHeader(config);
+ if (config.authHeader) {
+ const authHeaderValue =
+ typeof config.authHeader === "function"
+ ? config.authHeader()
+ : String(config.authHeader);
+ headers.set("Authorization", authHeaderValue);
+ }
+
+ if (config.apiKey) {
+ headers.set("x-api-key", config.apiKey);
+ }
+
+ // Update custom headers last to allow them to over-write the defaults.
+ updateCustomHeaders(config);
+ if (config.headers) {
+ for (const [header, value] of Object.entries(config.headers)) {
+ headers.set(header, value);
+ }
+ }
+
+ return headers;
+}
diff --git a/products/userale/packages/flagon-userale/src/exporters/http-json.ts b/products/userale/packages/flagon-userale/src/exporters/http-json.ts
new file mode 100644
index 0000000..79379e4
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/http-json.ts
@@ -0,0 +1,126 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Configuration } from "@/configure";
+import type { Logging } from "@/types";
+import { buildHeaders } from "./headers";
+import type { ExportOptions, ExportResult, LogExporter } from "./types";
+
+const MAX_KEEPALIVE_BYTES = 48 * 1024;
+
+/**
+ * Splits a log array into sub-batches whose serialized JSON size stays under
+ * MAX_KEEPALIVE_BYTES so browser pagehide/keepalive requests do not reject.
+ */
+export function chunkLogsForKeepalive<T>(
+ logs: Array<T>,
+ serialize: (batch: Array<T>) => string,
+): Array<string> {
+ const full = serialize(logs);
+ if (full.length <= MAX_KEEPALIVE_BYTES || logs.length <= 1) {
+ return [full];
+ }
+ const mid = Math.ceil(logs.length / 2);
+ return [
+ ...chunkLogsForKeepalive(logs.slice(0, mid), serialize),
+ ...chunkLogsForKeepalive(logs.slice(mid), serialize),
+ ];
+}
+
+export class HttpJsonExporter implements LogExporter {
+ private config: Configuration;
+
+ constructor(config: Configuration) {
+ this.config = config;
+ }
+
+ protected serialize(logs: Array<Logging.Log>): string {
+ return JSON.stringify(logs);
+ }
+
+ protected getEndpoint(): string {
+ return this.config.url;
+ }
+
+ public async export(
+ logs: Array<Logging.Log>,
+ options?: ExportOptions,
+ ): Promise<ExportResult> {
+ const headers = buildHeaders(this.config);
+ const endpoint = this.getEndpoint();
+ const keepalive = Boolean(options?.keepalive);
+ const retries = options?.retries ?? 0;
+
+ if (keepalive) {
+ const payloads = chunkLogsForKeepalive(logs, (batch) =>
+ this.serialize(batch),
+ );
+ try {
+ await Promise.all(
+ payloads.map((body) =>
+ fetch(endpoint, {
+ keepalive: true,
+ method: "POST",
+ headers,
+ body,
+ }),
+ ),
+ );
+ return { success: true };
+ } catch (err) {
+ const error = err instanceof Error ? err : new Error(String(err));
+ console.error(error);
+ return { success: false, error };
+ }
+ }
+
+ const body = this.serialize(logs);
+
+ async function attemptSend(remainingRetries: number): Promise<void> {
+ try {
+ const response = await fetch(endpoint, {
+ method: "POST",
+ headers,
+ body,
+ });
+
+ if (!response.ok) {
+ if (remainingRetries > 0) {
+ return attemptSend(remainingRetries - 1);
+ }
+ throw new Error(`Failed to send logs: ${response.statusText}`);
+ }
+ } catch (error) {
+ if (remainingRetries > 0) {
+ return attemptSend(remainingRetries - 1);
+ }
+ throw error;
+ }
+ }
+
+ await attemptSend(retries);
+ return { success: true };
+ }
+
+ public async flush(): Promise<void> {
+ return Promise.resolve();
+ }
+
+ public async shutdown(): Promise<void> {
+ return Promise.resolve();
+ }
+}
diff --git a/products/userale/packages/flagon-userale/src/exporters/index.ts b/products/userale/packages/flagon-userale/src/exporters/index.ts
new file mode 100644
index 0000000..c0721ac
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/index.ts
@@ -0,0 +1,71 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Configuration } from "@/configure";
+import { buildHeaders } from "./headers";
+import { HttpJsonExporter, chunkLogsForKeepalive } from "./http-json";
+import {
+ ProtoJsonExporter,
+ toProtoLogBatch,
+ toProtoUserALELog,
+} from "./proto-json";
+import type {
+ ExportOptions,
+ ExportResult,
+ ExporterType,
+ LogExporter,
+} from "./types";
+import { WebSocketExporter } from "./websocket";
+
+export {
+ buildHeaders,
+ chunkLogsForKeepalive,
+ HttpJsonExporter,
+ ProtoJsonExporter,
+ toProtoLogBatch,
+ toProtoUserALELog,
+ WebSocketExporter,
+};
+export type { ExportOptions, ExportResult, ExporterType, LogExporter };
+
+/**
+ * Factory that creates the appropriate LogExporter for the given configuration.
+ */
+export function createExporter(config: Configuration): LogExporter {
+ if (config.exporter) {
+ return config.exporter;
+ }
+
+ try {
+ const url = new URL(config.url);
+ if (
+ url.protocol === "ws:" ||
+ url.protocol === "wss:" ||
+ config.exporterType === "websocket"
+ ) {
+ return new WebSocketExporter(config);
+ }
+ } catch {
+ // Fallback to HTTP exporter if config.url is not a full URL (e.g. relative path in tests)
+ }
+
+ if (config.exporterType === "proto-json") {
+ return new ProtoJsonExporter(config);
+ }
+
+ return new HttpJsonExporter(config);
+}
diff --git a/products/userale/packages/flagon-userale/src/exporters/proto-json.ts b/products/userale/packages/flagon-userale/src/exporters/proto-json.ts
new file mode 100644
index 0000000..45a31e7
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/proto-json.ts
@@ -0,0 +1,219 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Logging } from "@/types";
+import { HttpJsonExporter } from "./http-json";
+
+const KNOWN_CUSTOM_LOG_KEYS = new Set([
+ "pageUrl",
+ "pageTitle",
+ "pageReferrer",
+ "userAgent",
+ "clientTime",
+ "scrnRes",
+ "logType",
+ "userAction",
+ "details",
+ "userId",
+ "toolVersion",
+ "toolName",
+ "useraleVersion",
+ "sessionId",
+ "httpSessionId",
+ "browserSessionId",
+]);
+
+function buildProtoMetadata(log: Logging.Log): Logging.JSONObject {
+ const scrnRes = log.scrnRes as
+ { width?: number; height?: number } | undefined;
+ const metadata: Logging.JSONObject = {
+ pageUrl: typeof log.pageUrl === "string" ? log.pageUrl : "",
+ pageTitle: typeof log.pageTitle === "string" ? log.pageTitle : "",
+ pageReferrer: typeof log.pageReferrer === "string" ? log.pageReferrer : "",
+ userAgent: typeof log.userAgent === "string" ? log.userAgent : "",
+ clientTime: String(
+ typeof log.clientTime === "number"
+ ? Math.trunc(log.clientTime)
+ : typeof log.startTime === "number"
+ ? Math.trunc(log.startTime)
+ : 0,
+ ),
+ };
+
+ if (scrnRes && typeof scrnRes === "object") {
+ metadata.screenResolution = {
+ width: typeof scrnRes.width === "number" ? Math.trunc(scrnRes.width) : 0,
+ height:
+ typeof scrnRes.height === "number" ? Math.trunc(scrnRes.height) : 0,
+ };
+ }
+
+ if (typeof log.userId === "string") metadata.userId = log.userId;
+ if (typeof log.sessionId === "string") metadata.sessionId = log.sessionId;
+ if (typeof log.httpSessionId === "string")
+ metadata.httpSessionId = log.httpSessionId;
+ if (typeof log.browserSessionId === "string")
+ metadata.browserSessionId = log.browserSessionId;
+ if (typeof log.toolName === "string") metadata.toolName = log.toolName;
+ if (typeof log.toolVersion === "string")
+ metadata.toolVersion = log.toolVersion;
+ if (typeof log.useraleVersion === "string")
+ metadata.useraleVersion = log.useraleVersion;
+
+ return metadata;
+}
+
+function toStringAttributes(
+ attrs: unknown,
+): Record<string, string> | undefined {
+ if (!attrs || typeof attrs !== "object" || Array.isArray(attrs)) {
+ return undefined;
+ }
+ const out: Record<string, string> = {};
+ for (const [k, v] of Object.entries(attrs)) {
+ out[k] = typeof v === "string" ? v : JSON.stringify(v);
+ }
+ return out;
+}
+
+/**
+ * Converts a flat UserALE log entry into the proto3 canonical JSON structure
+ * defined by apache.flagon.userale.v1.UserALELog in log.proto (#142, #143).
+ */
+export function toProtoUserALELog(log: Logging.Log): Logging.JSONObject {
+ const metadata = buildProtoMetadata(log);
+ const logType = log.logType;
+
+ if (logType === "raw") {
+ const loc = log.location as
+ { x?: number | null; y?: number | null } | undefined;
+ const location: Logging.JSONObject = {};
+ if (loc && typeof loc === "object") {
+ if (typeof loc.x === "number") location.x = loc.x;
+ if (typeof loc.y === "number") location.y = loc.y;
+ }
+
+ const raw: Logging.JSONObject = {
+ metadata,
+ target: typeof log.target === "string" ? log.target : "",
+ path: Array.isArray(log.path) ? (log.path as string[]) : [],
+ eventType: typeof log.type === "string" ? log.type : "",
+ location,
+ userAction: Boolean(log.userAction),
+ };
+
+ if (typeof log.microTime === "number") {
+ raw.microTime = log.microTime;
+ }
+ if (
+ log.details &&
+ typeof log.details === "object" &&
+ !Array.isArray(log.details)
+ ) {
+ raw.details = log.details as Logging.JSONObject;
+ }
+ const strAttrs = toStringAttributes(log.attributes);
+ if (strAttrs) {
+ raw.attributes = strAttrs;
+ }
+ if (
+ log.style &&
+ typeof log.style === "object" &&
+ !Array.isArray(log.style)
+ ) {
+ raw.style = log.style as Logging.JSONObject;
+ }
+
+ return {
+ logType: "LOG_TYPE_RAW",
+ raw,
+ };
+ }
+
+ if (logType === "interval") {
+ const interval: Logging.JSONObject = {
+ metadata,
+ target: typeof log.target === "string" ? log.target : "",
+ path: Array.isArray(log.path) ? (log.path as string[]) : [],
+ eventType: typeof log.type === "string" ? log.type : "",
+ count: typeof log.count === "number" ? Math.trunc(log.count) : 0,
+ duration: String(
+ typeof log.duration === "number" ? Math.trunc(log.duration) : 0,
+ ),
+ startTime: String(
+ typeof log.startTime === "number" ? Math.trunc(log.startTime) : 0,
+ ),
+ endTime: String(
+ typeof log.endTime === "number" ? Math.trunc(log.endTime) : 0,
+ ),
+ targetChange: Boolean(log.targetChange),
+ typeChange: Boolean(log.typeChange),
+ userAction: Boolean(log.userAction),
+ };
+
+ return {
+ logType: "LOG_TYPE_INTERVAL",
+ interval,
+ };
+ }
+
+ const customFields: Logging.JSONObject = {};
+ for (const [key, value] of Object.entries(log)) {
+ if (!KNOWN_CUSTOM_LOG_KEYS.has(key) && value !== undefined) {
+ customFields[key] = value;
+ }
+ }
+
+ const custom: Logging.JSONObject = {
+ metadata,
+ userAction: Boolean(log.userAction),
+ customFields,
+ };
+
+ if (
+ log.details &&
+ typeof log.details === "object" &&
+ !Array.isArray(log.details)
+ ) {
+ custom.details = log.details as Logging.JSONObject;
+ }
+
+ return {
+ logType: "LOG_TYPE_CUSTOM",
+ custom,
+ };
+}
+
+/**
+ * Converts an array of UserALE logs into an apache.flagon.userale.v1.LogBatch
+ * proto3 JSON object.
+ */
+export function toProtoLogBatch(logs: Array<Logging.Log>): Logging.JSONObject {
+ return {
+ logs: logs.map(toProtoUserALELog),
+ };
+}
+
+/**
+ * Exporter that serializes UserALE logs using the apache.flagon.userale.v1
+ * Protobuf JSON schema (#142, #143) with zero runtime protobuf dependencies.
+ */
+export class ProtoJsonExporter extends HttpJsonExporter {
+ protected override serialize(logs: Array<Logging.Log>): string {
+ return JSON.stringify(toProtoLogBatch(logs));
+ }
+}
diff --git a/products/userale/packages/flagon-userale/src/exporters/types.ts b/products/userale/packages/flagon-userale/src/exporters/types.ts
new file mode 100644
index 0000000..5a1ebcb
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/types.ts
@@ -0,0 +1,40 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Logging } from "@/types";
+
+export type ExporterType =
+ "http-json" | "proto-json" | "otlp" | "websocket" | "custom";
+
+export interface ExportOptions {
+ keepalive?: boolean;
+ retries?: number;
+}
+
+export interface ExportResult {
+ success: boolean;
+ error?: Error;
+}
+
+export interface LogExporter {
+ export(
+ logs: Array<Logging.Log>,
+ options?: ExportOptions,
+ ): Promise<ExportResult>;
+ flush?(): Promise<void>;
+ shutdown?(): Promise<void>;
+}
diff --git a/products/userale/packages/flagon-userale/src/exporters/websocket.ts b/products/userale/packages/flagon-userale/src/exporters/websocket.ts
new file mode 100644
index 0000000..6132778
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/websocket.ts
@@ -0,0 +1,48 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Configuration } from "@/configure";
+import type { Logging } from "@/types";
+import type { ExportResult, LogExporter } from "./types";
+
+export class WebSocketExporter implements LogExporter {
+ private wsock: WebSocket;
+
+ constructor(config: Configuration) {
+ this.wsock = new WebSocket(config.url);
+ }
+
+ public async export(logs: Array<Logging.Log>): Promise<ExportResult> {
+ const data = JSON.stringify(logs);
+ this.wsock.send(data);
+ return { success: true };
+ }
+
+ public async flush(): Promise<void> {
+ return Promise.resolve();
+ }
+
+ public async shutdown(): Promise<void> {
+ if (
+ typeof WebSocket !== "undefined" &&
+ this.wsock.readyState === WebSocket.OPEN
+ ) {
+ this.wsock.close();
+ }
+ return Promise.resolve();
+ }
+}
diff --git a/products/userale/packages/flagon-userale/src/getInitialSettings.ts b/products/userale/packages/flagon-userale/src/getInitialSettings.ts
index 85e3d78..14118db 100644
--- a/products/userale/packages/flagon-userale/src/getInitialSettings.ts
+++ b/products/userale/packages/flagon-userale/src/getInitialSettings.ts
@@ -38,6 +38,8 @@ export function getInitialSettings(): Settings.Config {
autostart: true,
browserSessionId: null,
custIndex: null,
+ exporter: null,
+ exporterType: "http-json",
headers: null,
httpSessionId: null,
logCountThreshold: +5,
@@ -83,12 +85,17 @@ export function getInitialSettings(): Settings.Config {
return null;
};
const headers = get("data-headers");
+ const exporterAttr = (get("data-exporter-type") ||
+ get("data-exporter") ||
+ "http-json") as Settings.ExporterType;
const settings: Settings.Config = {
apiKey: get("data-api-key") || null,
authHeader: get("data-auth") || null,
autostart: get("data-autostart") === "false" ? false : true,
browserSessionId: null,
custIndex: get("data-index") || null,
+ exporter: null,
+ exporterType: exporterAttr,
headers: headers ? JSON.parse(headers) : null,
httpSessionId: httpSessionId,
logCountThreshold: +(get("data-threshold") || 5),
diff --git a/products/userale/packages/flagon-userale/src/main.ts b/products/userale/packages/flagon-userale/src/main.ts
index dae8393..4934776 100644
--- a/products/userale/packages/flagon-userale/src/main.ts
+++ b/products/userale/packages/flagon-userale/src/main.ts
@@ -55,6 +55,21 @@ export {
getSelector as getSelector,
buildPath as buildPath,
} from "@/packageLogs";
+export {
+ buildHeaders,
+ createExporter,
+ HttpJsonExporter,
+ ProtoJsonExporter,
+ toProtoLogBatch,
+ toProtoUserALELog,
+ WebSocketExporter,
+} from "@/exporters";
+export type {
+ ExportOptions,
+ ExportResult,
+ ExporterType,
+ LogExporter,
+} from "@/exporters";
export type { Logging, Settings } from "@/types";
config.update({
diff --git a/products/userale/packages/flagon-userale/src/sendLogs.ts b/products/userale/packages/flagon-userale/src/sendLogs.ts
index 29cba74..f62b200 100644
--- a/products/userale/packages/flagon-userale/src/sendLogs.ts
+++ b/products/userale/packages/flagon-userale/src/sendLogs.ts
@@ -16,11 +16,30 @@
*/
import { Configuration } from "@/configure";
+import { buildHeaders, createExporter, type LogExporter } from "@/exporters";
import { Logging } from "@/types";
-import { updateAuthHeader, updateCustomHeaders } from "@/utils";
+
+export { buildHeaders };
let sendIntervalId: string | number | NodeJS.Timeout | undefined;
-let wsock: WebSocket;
+let activeExporter: LogExporter | null = null;
+let activeExporterKey: string | null = null;
+let activeCustomExporter: LogExporter | null = null;
+
+function resolveExporter(config: Configuration): LogExporter {
+ const key = `${config.url}|${config.exporterType ?? "http-json"}`;
+ if (
+ activeExporter &&
+ activeExporterKey === key &&
+ activeCustomExporter === (config.exporter ?? null)
+ ) {
+ return activeExporter;
+ }
+ activeExporter = createExporter(config);
+ activeExporterKey = key;
+ activeCustomExporter = config.exporter ?? null;
+ return activeExporter;
+}
/**
* Initializes the log queue processors.
@@ -32,20 +51,24 @@ export function initSender(logs: Array<Logging.Log>, config: Configuration) {
clearInterval(sendIntervalId);
}
- const url = new URL(config.url);
- if (
- (config.apiKey || config.authHeader) &&
- url.protocol === "http:" &&
- !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
- ) {
- console.warn(
- "[UserALE] Sending credentials over plaintext HTTP. Use HTTPS in production.",
- );
- }
- if (url.protocol === "ws:" || url.protocol === "wss:") {
- wsock = new WebSocket(config.url);
+ try {
+ const url = new URL(config.url);
+ if (
+ (config.apiKey || config.authHeader) &&
+ url.protocol === "http:" &&
+ !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+ ) {
+ console.warn(
+ "[UserALE] Sending credentials over plaintext HTTP. Use HTTPS in production.",
+ );
+ }
+ } catch {
+ // Ignore invalid URL during initialization if a custom exporter is used
}
+ activeExporter = null;
+ resolveExporter(config);
+
sendIntervalId = sendOnInterval(logs, config);
sendOnClose(logs, config);
}
@@ -73,11 +96,11 @@ export function sendOnInterval(
}, config.transmitInterval);
}
-// /**
-// * Attempts to flush the remaining logs when the window is closed.
-// * @param {Array<Logging.Log>} logs Array of logs to be flushed.
-// * @param {Configuration} config Configuration singleton to be read from.
-// */
+/**
+ * Attempts to flush the remaining logs when the window is closed.
+ * @param {Array<Logging.Log>} logs Array of logs to be flushed.
+ * @param {Configuration} config Configuration singleton to be read from.
+ */
export function sendOnClose(
logs: Array<Logging.Log>,
config: Configuration,
@@ -88,39 +111,18 @@ export function sendOnClose(
}
if (logs.length > 0) {
- const url = new URL(config.url);
-
- if (url.protocol === "ws:" || url.protocol === "wss:") {
- const data = JSON.stringify(logs);
- wsock.send(data);
- } else {
- const headers: HeadersInit = new Headers();
- headers.set("Content-Type", "application/json;charset=UTF-8");
-
- if (config.authHeader) {
- headers.set("Authorization", config.authHeader.toString());
- }
-
- if (config.apiKey) {
- headers.set("x-api-key", config.apiKey);
- }
-
- fetch(config.url, {
- keepalive: true,
- method: "POST",
- headers: headers,
- body: JSON.stringify(logs),
- }).catch((error) => {
- console.error(error);
- });
- }
+ const batch = logs.slice(0);
logs.splice(0); // clear log queue
+ const exporter = resolveExporter(config);
+ exporter.export(batch, { keepalive: true }).catch((error) => {
+ console.error(error);
+ });
}
});
}
/**
- * Sends the provided array of logs to the specified url,
+ * Sends the provided array of logs to the specified url via the active exporter,
* retrying the request up to the specified number of retries.
* @param {Array<Logging.Log>} logs Array of logs to send.
* @param {Configuration} config configuration singleton.
@@ -131,63 +133,6 @@ export async function sendLogs(
config: Configuration,
retries: number,
): Promise<void> {
- const data = JSON.stringify(logs);
- const url = new URL(config.url);
-
- if (url.protocol === "ws:" || url.protocol === "wss:") {
- wsock.send(data);
- return;
- }
-
- // Build headers
- const headers = new Headers({
- "Content-Type": "application/json;charset=UTF-8",
- });
-
- updateAuthHeader(config);
- if (config.authHeader) {
- const authHeaderValue =
- typeof config.authHeader === "function"
- ? config.authHeader()
- : config.authHeader;
- headers.set("Authorization", authHeaderValue);
- }
-
- if (config.apiKey) {
- headers.set("x-api-key", config.apiKey);
- }
-
- // Update custom headers last to allow them to over-write the defaults. This assumes
- // the user knows what they are doing and may want to over-write the defaults.
- updateCustomHeaders(config);
- if (config.headers) {
- for (const [header, value] of Object.entries(config.headers)) {
- headers.set(header, value);
- }
- }
-
- async function attemptSend(remainingRetries: number): Promise<void> {
- try {
- const response = await fetch(config.url, {
- method: "POST",
- headers,
- body: data,
- });
-
- if (!response.ok) {
- if (remainingRetries > 0) {
- return attemptSend(remainingRetries - 1);
- } else {
- throw new Error(`Failed to send logs: ${response.statusText}`);
- }
- }
- } catch (error) {
- if (remainingRetries > 0) {
- return attemptSend(remainingRetries - 1);
- }
- throw error;
- }
- }
-
- return attemptSend(retries);
+ const exporter = resolveExporter(config);
+ await exporter.export(logs, { retries });
}
diff --git a/products/userale/packages/flagon-userale/src/types.d.ts b/products/userale/packages/flagon-userale/src/types.d.ts
index 75c2af6..d7c0d35 100644
--- a/products/userale/packages/flagon-userale/src/types.d.ts
+++ b/products/userale/packages/flagon-userale/src/types.d.ts
@@ -14,6 +14,11 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
+import type {
+ ExporterType as ExporterMode,
+ LogExporter,
+} from "@/exporters/types";
+
export declare namespace Settings {
type Version = string | null;
type UserId = string | null;
@@ -25,11 +30,14 @@ export declare namespace Settings {
type CustomIndex = string | null;
type HeaderObject = { [key: string]: string };
type Headers = HeaderObject | null;
+ type ExporterType = ExporterMode;
+ type CustomExporter = LogExporter | null;
type ConfigValueTypes =
| string
| number
| boolean
| null
+ | undefined
| Version
| UserId
| SessionId
@@ -38,7 +46,9 @@ export declare namespace Settings {
| AuthHeader
| ApiKey
| CustomIndex
- | Headers;
+ | Headers
+ | ExporterType
+ | CustomExporter;
type TimeFunction = (() => number) | ((ts: number) => number);
@@ -52,6 +62,8 @@ export declare namespace Settings {
authHeader: AuthHeader;
browserSessionId: SessionId;
custIndex: CustomIndex;
+ exporter?: CustomExporter;
+ exporterType?: ExporterType;
headers: Headers;
httpSessionId: SessionId;
logCountThreshold: number;
diff --git a/products/userale/packages/flagon-userale/test/spec/exporters.spec.ts b/products/userale/packages/flagon-userale/test/spec/exporters.spec.ts
new file mode 100644
index 0000000..008ccc3
--- /dev/null
+++ b/products/userale/packages/flagon-userale/test/spec/exporters.spec.ts
@@ -0,0 +1,349 @@
+/**
+ * @jest-environment jsdom
+ */
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import "whatwg-fetch";
+import { Configuration } from "@/configure";
+import {
+ buildHeaders,
+ chunkLogsForKeepalive,
+ createExporter,
+ HttpJsonExporter,
+ ProtoJsonExporter,
+ toProtoLogBatch,
+ WebSocketExporter,
+} from "@/exporters";
+import { LogBatchSchema, LogType } from "@/gen/apache/flagon/userale/v1/log_pb";
+import { initSender, sendOnInterval } from "@/sendLogs";
+import {
+ registerAuthCallback,
+ registerHeadersCallback,
+ resetAuthCallback,
+ resetHeadersCallback,
+} from "@/utils";
+import { fromJson } from "@bufbuild/protobuf";
+
+import type { LogExporter } from "@/exporters";
+import type { Logging } from "@/types";
+import type { JsonValue } from "@bufbuild/protobuf";
+
+const config = Configuration.getInstance();
+
+describe("exporters", () => {
+ beforeEach(() => {
+ config.reset();
+ resetAuthCallback();
+ resetHeadersCallback();
+ });
+
+ describe("buildHeaders", () => {
+ it("merges string authHeader, custom headers callback, and apiKey", () => {
+ registerHeadersCallback(() => ({
+ "x-custom": "val",
+ }));
+ config.update({
+ authHeader: "Bearer test-token",
+ apiKey: "api-key-123",
+ });
+
+ const headers = buildHeaders(config);
+ expect(headers.get("Content-Type")).toBe(
+ "application/json;charset=UTF-8",
+ );
+ expect(headers.get("Authorization")).toBe("Bearer test-token");
+ expect(headers.get("x-api-key")).toBe("api-key-123");
+ expect(headers.get("x-custom")).toBe("val");
+ });
+
+ it("supports callback authHeader", () => {
+ registerAuthCallback(() => "Bearer dynamic-token");
+ const headers = buildHeaders(config);
+ expect(headers.get("Authorization")).toBe("Bearer dynamic-token");
+ });
+ });
+
+ describe("createExporter factory", () => {
+ it("creates HttpJsonExporter by default for http URLs", () => {
+ config.update({ url: "http://localhost:8000" });
+ const exporter = createExporter(config);
+ expect(exporter).toBeInstanceOf(HttpJsonExporter);
+ });
+
+ it("creates WebSocketExporter for ws:// or wss:// URLs", () => {
+ const wsSpy = jest.spyOn(global, "WebSocket").mockImplementation(
+ () =>
+ ({
+ readyState: 1,
+ send: jest.fn(),
+ close: jest.fn(),
+ }) as unknown as WebSocket,
+ );
+ config.update({ url: "ws://localhost:8000" });
+ const exporter = createExporter(config);
+ expect(exporter).toBeInstanceOf(WebSocketExporter);
+ wsSpy.mockRestore();
+ });
+
+ it("creates ProtoJsonExporter when exporterType is 'proto-json'", () => {
+ config.update({
+ url: "http://localhost:8000",
+ exporterType: "proto-json",
+ });
+ const exporter = createExporter(config);
+ expect(exporter).toBeInstanceOf(ProtoJsonExporter);
+ });
+
+ it("returns custom config.exporter when provided", () => {
+ const customExporter: LogExporter = {
+ export: jest.fn().mockResolvedValue({ success: true }),
+ };
+ config.update({ exporter: customExporter });
+ const exporter = createExporter(config);
+ expect(exporter).toBe(customExporter);
+ });
+
+ it("routes sendOnInterval through custom config.exporter", () => {
+ const customExporter: LogExporter = {
+ export: jest.fn().mockResolvedValue({ success: true }),
+ };
+ config.update({
+ on: true,
+ transmitInterval: 100,
+ logCountThreshold: 1,
+ exporter: customExporter,
+ });
+
+ const logs: Array<Logging.Log> = [{ target: "button#submit" }];
+ jest.useFakeTimers();
+ initSender(logs, config);
+ sendOnInterval(logs, config);
+
+ jest.advanceTimersByTime(100);
+ expect(customExporter.export).toHaveBeenCalledWith(
+ [{ target: "button#submit" }],
+ { retries: 0 },
+ );
+ jest.useRealTimers();
+ });
+ });
+
+ describe("chunkLogsForKeepalive", () => {
+ it("keeps small batches in a single chunk", () => {
+ const logs = [{ id: 1 }, { id: 2 }];
+ const chunks = chunkLogsForKeepalive(logs, (batch) =>
+ JSON.stringify(batch),
+ );
+ expect(chunks).toHaveLength(1);
+ expect(JSON.parse(chunks[0]!)).toEqual(logs);
+ });
+
+ it("splits batches that exceed MAX_KEEPALIVE_BYTES into multiple chunks", () => {
+ const logs = Array.from({ length: 10 }, (_, i) => ({
+ id: i,
+ payload: "x".repeat(8000),
+ }));
+ const chunks = chunkLogsForKeepalive(logs, (batch) =>
+ JSON.stringify(batch),
+ );
+ expect(chunks.length).toBeGreaterThan(1);
+ const reassembled = chunks.flatMap(
+ (chunk) => JSON.parse(chunk) as typeof logs,
+ );
+ expect(reassembled).toEqual(logs);
+ });
+ });
+
+ describe("ProtoJsonExporter & Protobuf v1 contract (#142, #143)", () => {
+ it("serializes raw, interval, and custom logs into valid apache.flagon.userale.v1.LogBatch JSON", () => {
+ const rawLog: Logging.Log = {
+ target: "button#buy",
+ path: ["button#buy", "div.card", "body", "html"],
+ pageUrl: "https://shop.example.com/product/42",
+ pageTitle: "Shop Example",
+ pageReferrer: "https://shop.example.com/",
+ browser: { browser: "chrome", version: "125.0" },
+ userAgent: "Mozilla/5.0 Chrome/125.0",
+ clientTime: 1712000000000,
+ scrnRes: { width: 1920, height: 1080 },
+ microTime: 123.45,
+ location: { x: 150, y: 320 },
+ type: "click",
+ logType: "raw",
+ userAction: true,
+ details: { button: 0, ctrl: false },
+ userId: "user-42",
+ toolVersion: "1.2.3",
+ toolName: "shop-web",
+ useraleVersion: "2.5.0",
+ sessionId: "sess-abc",
+ httpSessionId: "http-sess-1",
+ browserSessionId: "browser-sess-1",
+ attributes: { id: "buy", class: "btn primary" },
+ style: { color: "rgb(255, 255, 255)" },
+ };
+
+ const intervalLog: Logging.Log = {
+ target: "div.feed",
+ path: ["div.feed", "body", "html"],
+ pageUrl: "https://shop.example.com/product/42",
+ pageTitle: "Shop Example",
+ pageReferrer: "https://shop.example.com/",
+ userAgent: "Mozilla/5.0 Chrome/125.0",
+ count: 14,
+ duration: 480,
+ startTime: 1712000000000,
+ endTime: 1712000000480,
+ type: "mouseover",
+ logType: "interval",
+ targetChange: false,
+ typeChange: false,
+ userAction: false,
+ userId: "user-42",
+ toolVersion: "1.2.3",
+ toolName: "shop-web",
+ useraleVersion: "2.5.0",
+ sessionId: "sess-abc",
+ httpSessionId: "http-sess-1",
+ browserSessionId: "browser-sess-1",
+ };
+
+ const customLog: Logging.Log = {
+ pageUrl: "https://shop.example.com/product/42",
+ pageTitle: "Shop Example",
+ pageReferrer: "https://shop.example.com/",
+ userAgent: "Mozilla/5.0 Chrome/125.0",
+ clientTime: 1712000001000,
+ scrnRes: { width: 1920, height: 1080 },
+ logType: "custom",
+ userAction: true,
+ details: { checkoutStep: 2 },
+ customLabel: "checkout_started",
+ cartValue: 99.95,
+ userId: "user-42",
+ toolVersion: "1.2.3",
+ toolName: "shop-web",
+ useraleVersion: "2.5.0",
+ sessionId: "sess-abc",
+ httpSessionId: "http-sess-1",
+ browserSessionId: "browser-sess-1",
+ };
+
+ const protoBatchJson = toProtoLogBatch([rawLog, intervalLog, customLog]);
+
+ // Validate canonical Proto3 JSON deserialization against @bufbuild/protobuf LogBatchSchema
+ const decoded = fromJson(
+ LogBatchSchema,
+ protoBatchJson as unknown as JsonValue,
+ );
+ expect(decoded.logs).toHaveLength(3);
+
+ // 1. Raw log validation
+ const first = decoded.logs[0]!;
+ expect(first.logType).toBe(LogType.RAW);
+ expect(first.log.case).toBe("raw");
+ if (first.log.case === "raw") {
+ expect(first.log.value.target).toBe("button#buy");
+ expect(first.log.value.eventType).toBe("click");
+ expect(first.log.value.path).toEqual([
+ "button#buy",
+ "div.card",
+ "body",
+ "html",
+ ]);
+ expect(first.log.value.location?.x).toBe(150);
+ expect(first.log.value.location?.y).toBe(320);
+ expect(first.log.value.microTime).toBe(123.45);
+ expect(first.log.value.userAction).toBe(true);
+ expect(first.log.value.metadata?.pageUrl).toBe(
+ "https://shop.example.com/product/42",
+ );
+ expect(first.log.value.metadata?.clientTime).toBe(
+ BigInt(1712000000000),
+ );
+ expect(first.log.value.metadata?.screenResolution?.width).toBe(1920);
+ expect(first.log.value.metadata?.userId).toBe("user-42");
+ expect(first.log.value.details).toEqual({
+ button: 0,
+ ctrl: false,
+ });
+ expect(first.log.value.attributes).toEqual({
+ id: "buy",
+ class: "btn primary",
+ });
+ }
+
+ // 2. Interval log validation
+ const second = decoded.logs[1]!;
+ expect(second.logType).toBe(LogType.INTERVAL);
+ expect(second.log.case).toBe("interval");
+ if (second.log.case === "interval") {
+ expect(second.log.value.target).toBe("div.feed");
+ expect(second.log.value.count).toBe(14);
+ expect(second.log.value.duration).toBe(BigInt(480));
+ expect(second.log.value.startTime).toBe(BigInt(1712000000000));
+ expect(second.log.value.endTime).toBe(BigInt(1712000000480));
+ }
+
+ // 3. Custom log validation
+ const third = decoded.logs[2]!;
+ expect(third.logType).toBe(LogType.CUSTOM);
+ expect(third.log.case).toBe("custom");
+ if (third.log.case === "custom") {
+ expect(third.log.value.userAction).toBe(true);
+ expect(third.log.value.details).toEqual({ checkoutStep: 2 });
+ expect(third.log.value.customFields).toEqual({
+ customLabel: "checkout_started",
+ cartValue: 99.95,
+ });
+ }
+ });
+
+ it("exports LogBatch JSON over fetch when ProtoJsonExporter.export is called", async () => {
+ const fetchSpy = jest
+ .spyOn(global, "fetch")
+ .mockResolvedValue(new Response(null, { status: 200 }));
+
+ config.update({
+ url: "http://localhost:8000",
+ exporterType: "proto-json",
+ });
+
+ const exporter = new ProtoJsonExporter(config);
+ const result = await exporter.export([
+ {
+ target: "a#nav",
+ path: ["a#nav"],
+ type: "click",
+ logType: "raw",
+ clientTime: 1712000000000,
+ userAction: true,
+ },
+ ]);
+
+ expect(result.success).toBe(true);
+ expect(fetchSpy).toHaveBeenCalledTimes(1);
+ const bodyStr = fetchSpy.mock.calls[0]![1]!.body as string;
+ const parsed = JSON.parse(bodyStr) as JsonValue;
+ const decoded = fromJson(LogBatchSchema, parsed);
+ expect(decoded.logs).toHaveLength(1);
+ expect(decoded.logs[0]!.logType).toBe(LogType.RAW);
+
+ fetchSpy.mockRestore();
+ });
+ });
+});
diff --git a/products/userale/packages/flagon-userale/test/spec/sendLogs.spec.ts b/products/userale/packages/flagon-userale/test/spec/sendLogs.spec.ts
index 8d73234..bad6e83 100644
--- a/products/userale/packages/flagon-userale/test/spec/sendLogs.spec.ts
+++ b/products/userale/packages/flagon-userale/test/spec/sendLogs.spec.ts
@@ -20,7 +20,12 @@
import "whatwg-fetch";
import { Configuration } from "@/configure";
import { initSender, sendOnInterval, sendOnClose } from "@/sendLogs";
-import { registerAuthCallback, registerHeadersCallback } from "@/utils";
+import {
+ registerAuthCallback,
+ registerHeadersCallback,
+ resetAuthCallback,
+ resetHeadersCallback,
+} from "@/utils";
import type { Logging } from "@/types";
@@ -30,6 +35,8 @@ let xhrMock: Partial<XMLHttpRequest>;
describe("sendLogs", () => {
beforeEach(() => {
config.reset();
+ resetAuthCallback();
+ resetHeadersCallback();
xhrMock = {
open: jest.fn(),
send: jest.fn(),
@@ -300,4 +307,36 @@ describe("sendLogs", () => {
warnSpy.mockRestore();
});
+
+ it("includes callback authHeader and custom headers on pagehide (#133)", () => {
+ const fetchSpy = jest
+ .spyOn(global, "fetch")
+ .mockResolvedValue(new Response());
+
+ const authCallback = jest.fn().mockReturnValue("Bearer callback-token");
+ const headersCallback = jest.fn().mockReturnValue({
+ "x-custom-header": "custom-val",
+ });
+ registerAuthCallback(authCallback);
+ registerHeadersCallback(headersCallback);
+
+ config.update({
+ on: true,
+ url: "http://test.com",
+ apiKey: "key-123",
+ });
+
+ sendOnClose([{ foo: "bar" }], config);
+ global.window.dispatchEvent(new window.CustomEvent("pagehide"));
+
+ expect(fetchSpy).toHaveBeenCalled();
+ const lastCall = fetchSpy.mock.calls[fetchSpy.mock.calls.length - 1]!;
+ const callHeaders = lastCall[1]!.headers as Headers;
+ expect(callHeaders.get("Authorization")).toBe("Bearer callback-token");
+ expect(callHeaders.get("x-custom-header")).toBe("custom-val");
+ expect(callHeaders.get("x-api-key")).toBe("key-123");
+ expect(lastCall[1]!.keepalive).toBe(true);
+
+ fetchSpy.mockRestore();
+ });
});