mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-18 08:02:12 +00:00
feat(environment): add opt-in module, settings surface, API, and nightly fetch
Add the opt-in Environment module (default off), its Settings surface (home location search, travel overrides, backfill, with Open-Meteo attribution), the gated API routes (overview, home, geocode, travel CRUD, backfill), the nightly pg-boss fetch job with a lookback window plus on-demand backfill, the query keys, six-locale strings, and the regenerated OpenAPI. The module performs an outbound weather fetch tied to a coarse location, so it ships dark and the user turns it on deliberately; off means no job, no row, no egress.
This commit is contained in:
1 parent
cdee3e3efc
commit
088cad6c64
30 files changed
+1537
-2
No files matched your search
@@ -83,6 +83,7 @@ function moduleMap(
|
||||
insights: true,
|
||||
medications: true,
|
||||
doctorReport: true,
|
||||
environment: true,
|
||||
mcp: true,
|
||||
};
|
||||
return { ...base, ...overrides };
|
||||
|
||||
@@ -0,0 +1,185 @@
|
||||
/**
|
||||
* v1.25 (W-ENV) — nightly environmental-context fetch.
|
||||
*
|
||||
* For every account with the environmental-context module enabled AND a home
|
||||
* location set, fetch the daily weather/daylight for the recent uncovered days
|
||||
* and upsert into `EnvironmentContext`. A daily discovery tick (empty payload)
|
||||
* fans out one per-user job; the per-user job resolves each day's location
|
||||
* (travel override → home) and fetches a lookback window so the archive feed's
|
||||
* settling lag (a few days) is absorbed and any day missed across worker
|
||||
* reboots is re-attempted. The same handler also serves the on-demand backfill
|
||||
* (an explicit `{ userId, startDate, endDate }` payload from the settings
|
||||
* surface).
|
||||
*
|
||||
* Opt-in + privacy: the discovery filter requires both the module flag and a
|
||||
* home location, so a disabled account never triggers an outbound fetch. Egress
|
||||
* runs through `safeFetch` inside the Open-Meteo client. Recurring → pg-boss
|
||||
* (never a CLI script; the prod image strips `tsx`).
|
||||
*/
|
||||
import { prisma } from "@/lib/db";
|
||||
import type { PgBoss } from "pg-boss";
|
||||
import { getGlobalBoss } from "@/lib/jobs/boss-instance";
|
||||
import { isModuleEnabled } from "@/lib/modules/gate";
|
||||
import {
|
||||
ENVIRONMENT_LOOKBACK_DAYS,
|
||||
ENVIRONMENT_MAX_BACKFILL_DAYS,
|
||||
fetchAndStoreEnvironment,
|
||||
utcDayKey,
|
||||
} from "@/lib/environment/service";
|
||||
import { recordError } from "@/lib/jobs/worker-status";
|
||||
import { workerLog } from "./reminder/shared";
|
||||
|
||||
export const ENVIRONMENT_FETCH_QUEUE = "environment-fetch";
|
||||
|
||||
/** Daily 02:10 Europe/Berlin — early, before the 02:30+ maintenance window so
|
||||
* the night's weather rows exist before any briefing/insight pre-gen reads. */
|
||||
export const ENVIRONMENT_FETCH_CRON = "10 2 * * *";
|
||||
|
||||
export const ENVIRONMENT_FETCH_CONCURRENCY = 1;
|
||||
|
||||
const MS_PER_DAY = 24 * 60 * 60 * 1000;
|
||||
|
||||
/**
|
||||
* Per-user fetch payload. An empty payload (no `userId`) is the daily discovery
|
||||
* tick. `startDate`/`endDate` (YYYY-MM-DD) drive the on-demand backfill; omitted
|
||||
* ⇒ the default lookback window ending today.
|
||||
*/
|
||||
export interface EnvironmentFetchPayload {
|
||||
userId?: string;
|
||||
startDate?: string;
|
||||
endDate?: string;
|
||||
}
|
||||
|
||||
/** Resolve the date range for a per-user run (explicit range, else lookback). */
|
||||
function resolveRange(payload: EnvironmentFetchPayload): {
|
||||
startDate: string;
|
||||
endDate: string;
|
||||
} {
|
||||
const today = new Date();
|
||||
const endDate = payload.endDate ?? utcDayKey(today);
|
||||
const startDate =
|
||||
payload.startDate ??
|
||||
utcDayKey(
|
||||
new Date(today.getTime() - ENVIRONMENT_LOOKBACK_DAYS * MS_PER_DAY),
|
||||
);
|
||||
return { startDate, endDate };
|
||||
}
|
||||
|
||||
/**
|
||||
* Request-side enqueue for a single account: a default-lookback refresh (after
|
||||
* the user sets/changes their home, so weather appears without waiting for the
|
||||
* nightly tick) or an explicit-range backfill. No-ops cleanly when no global
|
||||
* boss is bound (e.g. a web-only deployment) — the nightly cron still covers it.
|
||||
* The lookback variant is singleton-coalesced per user; an explicit backfill
|
||||
* range is NOT coalesced so it always runs.
|
||||
*/
|
||||
export async function enqueueEnvironmentFetch(
|
||||
payload: EnvironmentFetchPayload & { userId: string },
|
||||
): Promise<boolean> {
|
||||
const boss = getGlobalBoss();
|
||||
if (!boss) return false;
|
||||
const options =
|
||||
payload.startDate || payload.endDate
|
||||
? undefined
|
||||
: { singletonKey: `environment-fetch:${payload.userId}` };
|
||||
await boss.send(ENVIRONMENT_FETCH_QUEUE, payload, options);
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Discovery fan-out: enqueue one per-user fetch job for every account with the
|
||||
* module on and a home location set. Idempotent (singletonKey-coalesced per
|
||||
* user). Returns counts for the worker log.
|
||||
*/
|
||||
export async function enqueueEnvironmentFetchDiscovery(
|
||||
boss: PgBoss,
|
||||
): Promise<{ enqueued: number; skipped: number }> {
|
||||
// Candidate set: a home location is required for any non-override day, so an
|
||||
// account without one cannot produce a row. The per-candidate module check
|
||||
// then enforces the opt-in flag + operator availability.
|
||||
const candidates = await prisma.user.findMany({
|
||||
where: { homeLat: { not: null }, homeLon: { not: null } },
|
||||
select: { id: true },
|
||||
});
|
||||
|
||||
let enqueued = 0;
|
||||
let skipped = 0;
|
||||
for (const { id } of candidates) {
|
||||
if (!(await isModuleEnabled(id, "environment"))) {
|
||||
skipped += 1;
|
||||
continue;
|
||||
}
|
||||
await boss.send(
|
||||
ENVIRONMENT_FETCH_QUEUE,
|
||||
{ userId: id } satisfies EnvironmentFetchPayload,
|
||||
{ singletonKey: `environment-fetch:${id}` },
|
||||
);
|
||||
enqueued += 1;
|
||||
}
|
||||
return { enqueued, skipped };
|
||||
}
|
||||
|
||||
/**
|
||||
* The queue handler. Empty payload ⇒ discovery fan-out; a `userId` payload ⇒
|
||||
* fetch + upsert for that user across the resolved range. Re-checks the module
|
||||
* gate on the per-user path so a backfill enqueued just before the user
|
||||
* disabled the module is a no-op.
|
||||
*/
|
||||
export async function handleEnvironmentFetch(
|
||||
boss: PgBoss,
|
||||
payload: EnvironmentFetchPayload,
|
||||
): Promise<void> {
|
||||
if (!payload.userId) {
|
||||
const { enqueued, skipped } = await enqueueEnvironmentFetchDiscovery(boss);
|
||||
workerLog(
|
||||
"info",
|
||||
`[environment-fetch] discovery enqueued=${enqueued} skipped=${skipped}`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
const userId = payload.userId;
|
||||
if (!(await isModuleEnabled(userId, "environment"))) {
|
||||
workerLog(
|
||||
"info",
|
||||
`[environment-fetch] user=${userId} module disabled — skipping`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
const { startDate, endDate } = resolveRange(payload);
|
||||
// Clamp the span so a crafted backfill can never fan out an unbounded range.
|
||||
const span = enumerateSpanDays(startDate, endDate);
|
||||
if (span > ENVIRONMENT_MAX_BACKFILL_DAYS) {
|
||||
workerLog(
|
||||
"error",
|
||||
`[environment-fetch] user=${userId} range ${startDate}..${endDate} (${span}d) exceeds cap — skipping`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
const result = await fetchAndStoreEnvironment({
|
||||
userId,
|
||||
startDate,
|
||||
endDate,
|
||||
});
|
||||
workerLog(
|
||||
"info",
|
||||
`[environment-fetch] user=${userId} ${startDate}..${endDate} stored=${result.stored} skipped=${result.skipped} fetches=${result.fetches}`,
|
||||
);
|
||||
} catch (err) {
|
||||
recordError();
|
||||
workerLog("error", `[environment-fetch] user=${userId} failed`, err);
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
function enumerateSpanDays(start: string, end: string): number {
|
||||
const [sy, sm, sd] = start.split("-").map(Number);
|
||||
const [ey, em, ed] = end.split("-").map(Number);
|
||||
const days = Math.round(
|
||||
(Date.UTC(ey, em - 1, ed) - Date.UTC(sy, sm - 1, sd)) / MS_PER_DAY,
|
||||
);
|
||||
return days + 1;
|
||||
}
|
||||
@@ -75,6 +75,13 @@ import {
|
||||
handleEncryptionKeyRotate,
|
||||
type EncryptionKeyRotatePayload,
|
||||
} from "@/lib/jobs/encryption-key-rotate";
|
||||
import {
|
||||
ENVIRONMENT_FETCH_QUEUE,
|
||||
ENVIRONMENT_FETCH_CRON,
|
||||
ENVIRONMENT_FETCH_CONCURRENCY,
|
||||
handleEnvironmentFetch,
|
||||
type EnvironmentFetchPayload,
|
||||
} from "@/lib/jobs/environment-fetch";
|
||||
import { recordError } from "@/lib/jobs/worker-status";
|
||||
import { workerLog, BOOT_BACKFILL_STAGGER_SECONDS } from "./shared";
|
||||
import { createAndSchedule, type ScheduleEntry } from "./registrar-shared";
|
||||
@@ -216,6 +223,12 @@ const MCP_TOKEN_CLEANUP_CRON = "0 4 * * *";
|
||||
const MED_NOTES_ENCRYPTION_BACKFILL_CRON = "5 4 * * *";
|
||||
|
||||
const allQueues = [
|
||||
// v1.25 (W-ENV) — nightly environmental-context fetch. A daily discovery tick
|
||||
// fans out one per-user job per opted-in account with a home location; the
|
||||
// queue also serves the on-demand backfill from the Environment settings
|
||||
// surface. Without this entry pg-boss never provisions it and both the cron
|
||||
// and the backfill button silently no-op.
|
||||
ENVIRONMENT_FETCH_QUEUE,
|
||||
DATA_BACKUP_QUEUE,
|
||||
RATE_LIMIT_CLEANUP_QUEUE,
|
||||
IDEMPOTENCY_CLEANUP_QUEUE,
|
||||
@@ -277,6 +290,9 @@ const allQueues = [
|
||||
];
|
||||
|
||||
const schedules: ScheduleEntry[] = [
|
||||
// v1.25 (W-ENV) — daily 02:10 Europe/Berlin discovery tick (empty payload)
|
||||
// that fans out one per-user environment fetch per opted-in account.
|
||||
[ENVIRONMENT_FETCH_QUEUE, ENVIRONMENT_FETCH_CRON],
|
||||
[DATA_BACKUP_QUEUE, DATA_BACKUP_CRON],
|
||||
[RATE_LIMIT_CLEANUP_QUEUE, RATE_LIMIT_CLEANUP_CRON],
|
||||
[IDEMPOTENCY_CLEANUP_QUEUE, IDEMPOTENCY_CLEANUP_CRON],
|
||||
@@ -601,6 +617,20 @@ export async function registerMaintenanceQueues(
|
||||
},
|
||||
);
|
||||
|
||||
// v1.25 (W-ENV) — nightly environment fetch. The daily discovery tick (empty
|
||||
// payload) fans out one per-user job per opted-in account; the queue also
|
||||
// serves the on-demand backfill payloads from the settings surface. Serial
|
||||
// concurrency so the staggered outbound fetches never crowd the request pool.
|
||||
await boss.work<EnvironmentFetchPayload>(
|
||||
ENVIRONMENT_FETCH_QUEUE,
|
||||
{ localConcurrency: ENVIRONMENT_FETCH_CONCURRENCY },
|
||||
async (jobs) => {
|
||||
for (const job of jobs) {
|
||||
await handleEnvironmentFetch(boss, job.data);
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
return allQueues;
|
||||
}
|
||||
|
||||
|
||||
@@ -352,10 +352,15 @@ describe("resolveModuleEnabled — mcp module (opt-in, default-OFF)", () => {
|
||||
});
|
||||
|
||||
describe("registry — opt-in marker", () => {
|
||||
it("marks only the mcp module opt-in (every other module is default-on)", () => {
|
||||
it("marks the mcp + environment modules opt-in (every other module is default-on)", () => {
|
||||
expect(isOptInModule("mcp")).toBe(true);
|
||||
// v1.25 (W-ENV) — the environmental-context module is opt-in too: it
|
||||
// performs an outbound weather fetch tied to a coarse location, so it ships
|
||||
// dark like the remote MCP endpoint.
|
||||
expect(isOptInModule("environment")).toBe(true);
|
||||
const optIn = new Set(["mcp", "environment"]);
|
||||
for (const key of MODULE_KEYS) {
|
||||
if (key === "mcp") continue;
|
||||
if (optIn.has(key)) continue;
|
||||
expect(isOptInModule(key)).toBe(false);
|
||||
}
|
||||
});
|
||||
|
||||
@@ -115,6 +115,12 @@ export const MODULE_KEYS = [
|
||||
// re-enabling finds the rows intact.
|
||||
"medications",
|
||||
"doctorReport",
|
||||
// v1.25.0 (W-ENV) — environmental-context module. Like `mcp`, it is OPT-IN
|
||||
// (off by default): it performs an outbound weather fetch tied to where the
|
||||
// user physically is (a coarse home / travel location), so opt-in is the
|
||||
// right privacy default. With it off no job runs, no row is written, and no
|
||||
// egress happens. The `optIn` marker inverts the per-user default.
|
||||
"environment",
|
||||
// v1.22.0 — the remote Model Context Protocol endpoint (`/mcp`). Unlike
|
||||
// every other module this is OPT-IN (off by default): it exposes a new
|
||||
// external-assistant attack surface, so it ships dark and the operator /
|
||||
@@ -256,6 +262,17 @@ export const MODULE_REGISTRY: Readonly<Record<ModuleKey, ModuleDefinition>> =
|
||||
descriptionKey: "modules.doctorReport.description",
|
||||
category: "export",
|
||||
},
|
||||
environment: {
|
||||
key: "environment",
|
||||
labelKey: "modules.environment.label",
|
||||
descriptionKey: "modules.environment.description",
|
||||
category: "device",
|
||||
// Off by default: performs an outbound weather fetch tied to a coarse
|
||||
// location, so it ships dark and the user turns it on deliberately. The
|
||||
// home location + travel overrides + backfill live on the dedicated
|
||||
// Environment settings surface (rendered when the module is on).
|
||||
optIn: true,
|
||||
},
|
||||
mcp: {
|
||||
key: "mcp",
|
||||
labelKey: "modules.mcp.label",
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
/**
|
||||
* Query keys — environmental-context module (v1.25, W-ENV). The overview
|
||||
* (home + travel overrides + stored-day summary) and the geocoding search.
|
||||
* Part of the centralized factory; aggregated in `./index.ts`.
|
||||
*/
|
||||
export const environmentKeys = {
|
||||
/**
|
||||
* `environment()` is the root prefix every environment write (set home, add /
|
||||
* remove a travel override, trigger a backfill) invalidates through, so the
|
||||
* settings surface repaints in lockstep.
|
||||
*/
|
||||
environment: () => ["environment"] as const,
|
||||
/** Geocoding search results for a query string (cached per query). */
|
||||
environmentGeocode: (query: string) =>
|
||||
["environment", "geocode", query] as const,
|
||||
};
|
||||
@@ -21,6 +21,7 @@ import { coachKeys } from "./coach";
|
||||
import { familyHistoryKeys } from "./family-history";
|
||||
import { cycleKeys } from "./cycle";
|
||||
import { dashboardKeys } from "./dashboard";
|
||||
import { environmentKeys } from "./environment";
|
||||
import { illnessKeys } from "./illness";
|
||||
import { insightsKeys } from "./insights";
|
||||
import { integrationKeys } from "./integrations";
|
||||
@@ -52,6 +53,7 @@ export const queryKeys = {
|
||||
...mentalHealthKeys,
|
||||
...allergyKeys,
|
||||
...familyHistoryKeys,
|
||||
...environmentKeys,
|
||||
};
|
||||
|
||||
/**
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
/**
|
||||
* v1.25 (W-ENV) — environmental-context request validation.
|
||||
*
|
||||
* The home location, the travel overrides, and the backfill span. Coordinates
|
||||
* are bounded to valid lat/lon; the labels are length-capped plaintext (a city
|
||||
* name, never a quasi-identifier). Dates are strict YYYY-MM-DD. The shared
|
||||
* shapes are reused by the OpenAPI registry so the wire contract stays
|
||||
* single-source.
|
||||
*/
|
||||
import { z } from "zod/v4";
|
||||
|
||||
/** Strict YYYY-MM-DD calendar day. */
|
||||
export const dayStringSchema = z
|
||||
.string()
|
||||
.regex(/^\d{4}-\d{2}-\d{2}$/, "Expected a YYYY-MM-DD date");
|
||||
|
||||
const latSchema = z.number().gte(-90).lte(90);
|
||||
const lonSchema = z.number().gte(-180).lte(180);
|
||||
const labelSchema = z.string().trim().min(1).max(200);
|
||||
|
||||
/** A coarse home location set in settings (city-level granularity). */
|
||||
export const homeLocationSchema = z
|
||||
.object({
|
||||
lat: latSchema,
|
||||
lon: lonSchema,
|
||||
label: labelSchema,
|
||||
/** IANA timezone (anchors the stored day-key). */
|
||||
timezone: z.string().trim().min(1).max(64),
|
||||
})
|
||||
.strict();
|
||||
|
||||
export type HomeLocationInput = z.infer<typeof homeLocationSchema>;
|
||||
|
||||
/** A manual travel override covering an inclusive date range. */
|
||||
export const travelLocationSchema = z
|
||||
.object({
|
||||
startDate: dayStringSchema,
|
||||
endDate: dayStringSchema,
|
||||
lat: latSchema,
|
||||
lon: lonSchema,
|
||||
label: labelSchema,
|
||||
})
|
||||
.strict()
|
||||
.refine((v) => v.startDate <= v.endDate, {
|
||||
message: "startDate must be on or before endDate",
|
||||
path: ["endDate"],
|
||||
});
|
||||
|
||||
export type TravelLocationInput = z.infer<typeof travelLocationSchema>;
|
||||
|
||||
/** A backfill request: fetch + store the environment rows over a date range. */
|
||||
export const environmentBackfillSchema = z
|
||||
.object({
|
||||
startDate: dayStringSchema,
|
||||
endDate: dayStringSchema,
|
||||
})
|
||||
.strict()
|
||||
.refine((v) => v.startDate <= v.endDate, {
|
||||
message: "startDate must be on or before endDate",
|
||||
path: ["endDate"],
|
||||
});
|
||||
|
||||
export type EnvironmentBackfillInput = z.infer<
|
||||
typeof environmentBackfillSchema
|
||||
>;
|
||||
|
||||
/** Geocoding search query (`?q=`). */
|
||||
export const geocodeQuerySchema = z
|
||||
.object({ q: z.string().trim().min(1).max(120) })
|
||||
.strict();
|
||||
Reference in new issue
Block a user