@iann29/rastro 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/component/http.ts

@@ -1,19 +1,33 @@
 import { httpRouter } from "convex/server";
 import { ConvexError } from "convex/values";
 import type { Id } from "./_generated/dataModel.js";
-import { api } from "./_generated/api.js";
-import { httpAction } from "./_generated/server.js";
-import { MAX_BATCH_BYTES } from "./constants.js";
+import { api, internal } from "./_generated/api.js";
+import { env, httpAction } from "./_generated/server.js";
+import {
+  MAX_BATCH_BYTES,
+  MAX_BATCH_EVENT_GROUPS,
+  MAX_BATCH_EVENTS,
+  RATE_LIMIT_WINDOW_MS,
+} from "./constants.js";
+import {
+  classifyIp,
+  geoIpDailyLimit,
+  geoIpStatus,
+  isTrustedProxyRequest,
+  readRequestMetadata,
+  resolveClientIp,
+  resolveGeoIp,
+} from "./geo.js";
 import { isPlainRecord } from "./guards.js";
+import { sanitizeEvent } from "./sanitize.js";
 import type { TrackerEvent } from "./validators.js";
 import {
   TRACKER_GZIP_BASE64,
   TRACKER_GZIP_BYTES,
 } from "../tracker/generated.js";
 
-const TRACKER_GZIP = Uint8Array.from(
-  atob(TRACKER_GZIP_BASE64),
-  (character) => character.charCodeAt(0),
+const TRACKER_GZIP = Uint8Array.from(atob(TRACKER_GZIP_BASE64), (character) =>
+  character.charCodeAt(0),
 );
 
 const http = httpRouter();
@@ -22,9 +36,16 @@ http.route({
   path: "/events",
   method: "POST",
   handler: httpAction(async (ctx, request) => {
+    const requestId = crypto.randomUUID();
     const origin = request.headers.get("origin");
-    if (!origin) return json({ error: { code: "ORIGIN_REQUIRED" } }, 400);
-    const headers = corsHeaders(origin);
+    if (!origin) {
+      return json(
+        { error: { code: "ORIGIN_REQUIRED" } },
+        400,
+        requestIdHeaders(requestId),
+      );
+    }
+    const headers = corsHeaders(origin, requestId);
     const contentLength = Number(request.headers.get("content-length"));
     if (Number.isFinite(contentLength) && contentLength > MAX_BATCH_BYTES) {
       return json(
@@ -51,7 +72,8 @@ http.route({
         {
           error: {
             code: "INVALID_BODY",
-            message: error instanceof Error ? error.message : "invalid JSON body",
+            message:
+              error instanceof Error ? error.message : "invalid JSON body",
           },
         },
         400,
@@ -59,12 +81,15 @@ http.route({
       );
     }
 
-    const userAgent = request.headers.get("user-agent") ?? "";
+    const trustProxy = env.RASTRO_TRUST_PROXY === "true";
+    const metadata = await readRequestMetadata(ctx);
+    const proxyRequestTrusted = isTrustedProxyRequest(metadata.ip, trustProxy);
+    const clientIp = resolveClientIp(metadata.ip, request.headers, trustProxy);
+    const edgeGeo = proxyRequestTrusted ? geoFromHeaders(request) : {};
+    const userAgent =
+      metadata.userAgent ?? request.headers.get("user-agent") ?? "";
     const context = {
-      country: firstHeader(request, ["x-vercel-ip-country", "cf-ipcountry"]),
-      city: decodeHeader(firstHeader(request, ["x-vercel-ip-city", "cf-ipcity"])),
-      latitude: numericHeader(request, ["x-vercel-ip-latitude", "cf-iplatitude"]),
-      longitude: numericHeader(request, ["x-vercel-ip-longitude", "cf-iplongitude"]),
+      ...edgeGeo,
       ...classifyUserAgent(userAgent),
     };
 
@@ -75,6 +100,56 @@ http.route({
         events: payload.events,
         context,
       });
+      if (
+        clientIp.ip &&
+        !hasCoordinates(edgeGeo) &&
+        geoIpStatus(env.RASTRO_GEOIP_PROVIDER, env.RASTRO_GEOIP_TOKEN) ===
+          "ready"
+      ) {
+        const events = enrichmentCandidateEvents(payload.events);
+        if (events) {
+          let stage: GeoIpFailureStage = "claim";
+          try {
+            const claim = await ctx.runMutation(
+              internal.geo.claimEnrichment,
+              {
+                siteId: payload.siteId as Id<"sites">,
+                events,
+                dailyLimit: geoIpDailyLimit(env.RASTRO_GEOIP_DAILY_LIMIT),
+              },
+            );
+            if (claim.sessionIds.length > 0) {
+              stage = "resolve";
+              const providerGeo = await resolveGeoIp(
+                clientIp.ip,
+                env.RASTRO_GEOIP_PROVIDER!,
+                env.RASTRO_GEOIP_TOKEN,
+              );
+              if (providerGeo) {
+                stage = "apply";
+                await ctx.runMutation(internal.geo.applyEnrichment, {
+                  siteId: payload.siteId as Id<"sites">,
+                  sessionIds: claim.sessionIds,
+                  events: claim.events,
+                  context: providerGeo,
+                });
+              } else {
+                logGeoIpFailure(
+                  requestId,
+                  stage,
+                  env.RASTRO_GEOIP_PROVIDER!,
+                );
+              }
+            }
+          } catch {
+            logGeoIpFailure(
+              requestId,
+              stage,
+              env.RASTRO_GEOIP_PROVIDER!,
+            );
+          }
+        }
+      }
       return json(result, 200, headers);
     } catch (error) {
       if (error instanceof ConvexError) {
@@ -85,9 +160,25 @@ http.route({
             : data.code === "RATE_LIMITED"
               ? 429
               : 400;
-        return json({ error: data }, status, headers);
+        return json(
+          { error: data },
+          status,
+          status === 429
+            ? {
+                ...headers,
+                "Retry-After": String(
+                  Math.ceil(RATE_LIMIT_WINDOW_MS / 1_000),
+                ),
+              }
+            : headers,
+        );
       }
-      return json({ error: { code: "INVALID_REQUEST" } }, 400, headers);
+      logInternalHttpError(requestId);
+      return json(
+        { error: { code: "INTERNAL_ERROR", requestId } },
+        500,
+        headers,
+      );
     }
   }),
 });
@@ -127,13 +218,35 @@ http.route({
   }),
 });
 
-
 http.route({
   path: "/health",
   method: "GET",
-  handler: httpAction(async () => {
+  handler: httpAction(async (ctx, request) => {
+    const trustProxy = env.RASTRO_TRUST_PROXY === "true";
+    const metadata = await readRequestMetadata(ctx);
+    const proxyRequestTrusted = isTrustedProxyRequest(metadata.ip, trustProxy);
+    const clientIp = resolveClientIp(metadata.ip, request.headers, trustProxy);
+    const provider = env.RASTRO_GEOIP_PROVIDER;
     return json(
-      { ok: true, component: "@iann29/rastro" },
+      {
+        ok: true,
+        component: "@iann29/rastro",
+        requestMetadata: {
+          runtimeIpKind: classifyIp(metadata.ip),
+          clientIpAvailable: clientIp.ip !== null,
+          clientIpSource: clientIp.source,
+          userAgentAvailable: metadata.userAgent !== null,
+        },
+        geoIp: {
+          provider: provider ?? null,
+          status: geoIpStatus(provider, env.RASTRO_GEOIP_TOKEN),
+          dailyLimit: geoIpDailyLimit(env.RASTRO_GEOIP_DAILY_LIMIT),
+          trustedProxy: trustProxy,
+          proxyRequestTrusted,
+          edgeHeadersAvailable:
+            proxyRequestTrusted && Object.keys(geoFromHeaders(request)).length > 0,
+        },
+      },
       200,
       {
         "Access-Control-Allow-Origin": "*",
@@ -143,8 +256,15 @@ http.route({
   }),
 });
 
-function parsePayload(value: unknown): { siteId: string; events: TrackerEvent[] } {
-  if (!isPlainRecord(value) || typeof value.siteId !== "string" || !Array.isArray(value.events)) {
+function parsePayload(value: unknown): {
+  siteId: string;
+  events: TrackerEvent[];
+} {
+  if (
+    !isPlainRecord(value) ||
+    typeof value.siteId !== "string" ||
+    !Array.isArray(value.events)
+  ) {
     throw new Error("body must contain siteId and events");
   }
   return { siteId: value.siteId, events: value.events.map(parseEvent) };
@@ -266,6 +386,90 @@ function optionalNumber(value: unknown, field: string): number | undefined {
   return value;
 }
 
+function enrichmentCandidateEvents(events: TrackerEvent[]):
+  | Array<{
+      eventId: string;
+      sessionId: string;
+      visitorId: string;
+      timestamp: number;
+      sequence: number;
+    }>
+  | undefined {
+  if (events.length === 0 || events.length > MAX_BATCH_EVENTS) return undefined;
+  const now = Date.now();
+  const sanitized = events.flatMap((event) => {
+    try {
+      return [sanitizeEvent(event, now)];
+    } catch {
+      return [];
+    }
+  });
+  const sessionIds = [...new Set(sanitized.map((event) => event.sessionId))];
+  if (
+    !sanitized.some((event) => event.sequence === 0) ||
+    sessionIds.length > MAX_BATCH_EVENT_GROUPS ||
+    sessionIds.some(
+      (sessionId) => sessionId.length === 0 || sessionId.length > 128,
+    )
+  ) {
+    return undefined;
+  }
+  return sanitized.map(
+    ({ eventId, sessionId, visitorId, timestamp, sequence }) => ({
+      eventId,
+      sessionId,
+      visitorId,
+      timestamp,
+      sequence,
+    }),
+  );
+}
+
+function geoFromHeaders(request: Request): {
+  country?: string;
+  city?: string;
+  latitude?: number;
+  longitude?: number;
+} {
+  const country = firstHeader(request, ["x-vercel-ip-country", "cf-ipcountry"]);
+  const city = decodeHeader(
+    firstHeader(request, ["x-vercel-ip-city", "cf-ipcity"]),
+  );
+  const latitude = numericHeader(request, [
+    "x-vercel-ip-latitude",
+    "cf-iplatitude",
+  ]);
+  const longitude = numericHeader(request, [
+    "x-vercel-ip-longitude",
+    "cf-iplongitude",
+  ]);
+  return {
+    ...(country ? { country } : {}),
+    ...(city ? { city } : {}),
+    ...(validCoordinates(latitude, longitude)
+      ? { latitude, longitude }
+      : {}),
+  };
+}
+
+function hasCoordinates(value: {
+  latitude?: number;
+  longitude?: number;
+}): boolean {
+  return value.latitude !== undefined && value.longitude !== undefined;
+}
+
+function validCoordinates(
+  latitude: number | undefined,
+  longitude: number | undefined,
+): latitude is number {
+  return latitude !== undefined &&
+    longitude !== undefined &&
+    latitude >= -90 &&
+    latitude <= 90 &&
+    longitude >= -180 &&
+    longitude <= 180;
+}
 
 function firstHeader(request: Request, names: string[]): string | undefined {
   for (const name of names) {
@@ -324,12 +528,45 @@ function classifyUserAgent(userAgent: string): {
   return { browser, os, device };
 }
 
-function corsHeaders(origin: string): HeadersInit {
+type GeoIpFailureStage = "claim" | "resolve" | "apply";
+
+function logInternalHttpError(requestId: string): void {
+  console.error(JSON.stringify({
+    level: "error",
+    event: "rastro.http.internal_error",
+    requestId,
+    route: "/events",
+    method: "POST",
+  }));
+}
+
+function logGeoIpFailure(
+  requestId: string,
+  stage: GeoIpFailureStage,
+  provider: "ipinfo" | "ipwhois",
+): void {
+  console.warn(JSON.stringify({
+    level: "warn",
+    event: "rastro.geoip.failure",
+    requestId,
+    route: "/events",
+    stage,
+    provider,
+  }));
+}
+
+function requestIdHeaders(requestId: string): Record<string, string> {
+  return { "X-Request-ID": requestId };
+}
+
+function corsHeaders(origin: string, requestId?: string): Record<string, string> {
   return {
     "Access-Control-Allow-Origin": origin,
     "Access-Control-Allow-Methods": "POST, OPTIONS",
     "Access-Control-Allow-Headers": "Content-Type",
+    "Access-Control-Expose-Headers": "X-Request-ID, Retry-After",
     "Access-Control-Max-Age": "86400",
+    ...(requestId ? requestIdHeaders(requestId) : {}),
     Vary: "Origin",
   };
 }