mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-21 03:26:07 +00:00
724c88c201
A mechanical prettier --write over server/src, server/tests, server/scripts and shared/src with the workspaces' .prettierrc; nothing but layout and import order changes, and every file keeps the same set of imports. shared is formatted throughout and its format baseline is empty. The server baseline keeps the 35 files that Prettier would grow past their lint:size limit (they need a split first, which is not a formatting change), and the generated entity files stay as their generator writes them.
442 lines
20 KiB
TypeScript
442 lines
20 KiB
TypeScript
import { ADDON_IDS } from '../../addons';
|
|
import type { User } from '../../types';
|
|
import { AddonGuard } from '../addons/addon.guard';
|
|
import { RequireAddon } from '../addons/require-addon.decorator';
|
|
import { CurrentUser } from '../auth-core/current-user.decorator';
|
|
import { JwtAuthGuard } from '../auth-core/jwt-auth.guard';
|
|
import { withRequestContext } from '../database/request-context';
|
|
import { TripAccessGuard } from '../permissions/trip-access.guard';
|
|
import { RealtimeService } from '../realtime/realtime.service';
|
|
import { DocSyncConfigService, type LinkRow } from './doc-sync-config.service';
|
|
import { PROVIDER_DISABLED } from './doc-sync.constants';
|
|
import {
|
|
DocsyncConnectionDto,
|
|
DocsyncConnectionTestDto,
|
|
DocsyncLinkDto,
|
|
DocsyncLinkUpdateDto,
|
|
DocsyncResolveConflictDto,
|
|
DocsyncScopeCreateDto,
|
|
DocsyncSyncNowDto,
|
|
} from './doc-sync.dto';
|
|
import { sameOrigin } from './doc-sync.helpers';
|
|
import { DocSyncService } from './doc-sync.service';
|
|
import { docFailed } from './document-provider';
|
|
import { DocumentProviderRegistry } from './document-provider.registry';
|
|
import { MikroORM } from '@mikro-orm/core';
|
|
import {
|
|
Body,
|
|
Controller,
|
|
Delete,
|
|
Get,
|
|
HttpCode,
|
|
HttpException,
|
|
Logger,
|
|
Param,
|
|
Patch,
|
|
Post,
|
|
Put,
|
|
Query,
|
|
Req,
|
|
UseGuards,
|
|
} from '@nestjs/common';
|
|
|
|
import type { Request } from 'express';
|
|
|
|
/**
|
|
* `/api/trips/:tripId/docsync`: a trip's document provider binding.
|
|
*
|
|
* Trip-scoped rather than user-scoped, and that is the whole point of the
|
|
* feature: one connection per trip, which every member reads through. The
|
|
* routes therefore sit under the trip, not under `/api/integrations`.
|
|
*
|
|
* Two shapes of answer, the split Dawarich already established: connection
|
|
* routes (`test`, `status`) answer 200 even when the provider is unreachable,
|
|
* with the reason in the body, because a form showing someone their own typo
|
|
* needs a field to render rather than an exception. Everything else answers the
|
|
* status the failure deserves.
|
|
*
|
|
* Only the trip owner may change a binding (plus an instance admin, who
|
|
* overrides trip permissions everywhere else too). It hands TREK a credential
|
|
* that usually reaches the owner's entire document archive, so widening this to
|
|
* every member would let any member point the trip at a folder the owner never
|
|
* meant to share. Reading the status is open to all members: they need to know
|
|
* where their documents are going.
|
|
*/
|
|
@Controller('api/trips/:tripId/docsync')
|
|
@UseGuards(AddonGuard, JwtAuthGuard, TripAccessGuard)
|
|
@RequireAddon(ADDON_IDS.DOCUMENTS, 'Documents')
|
|
export class DocSyncController {
|
|
private readonly logger = new Logger(DocSyncController.name);
|
|
|
|
constructor(
|
|
private readonly config: DocSyncConfigService,
|
|
private readonly sync: DocSyncService,
|
|
private readonly registry: DocumentProviderRegistry,
|
|
private readonly realtime: RealtimeService,
|
|
private readonly orm: MikroORM,
|
|
) {}
|
|
|
|
/**
|
|
* Tell the trip that a binding came or went.
|
|
*
|
|
* Whether a trip is bound decides whether its members see the sync button
|
|
* at all, and a run only pings when it moved a document. Binding two empty
|
|
* sides, or unbinding, moves nothing, so a member sitting on the Files tab
|
|
* kept the old answer until they left it. The whole room, the caller
|
|
* included: it is a ping to re-read, not a change to apply, and the owner's
|
|
* own button depends on it too once every provider is switched off.
|
|
*/
|
|
private announceBinding(link: Pick<LinkRow, 'id' | 'trip_id'>): void {
|
|
this.realtime.broadcast(link.trip_id, 'docsync:changed', { linkId: link.id, pulled: 0, pushed: 0 });
|
|
}
|
|
|
|
/**
|
|
* The trip owner or an instance admin, the same rule as `canManageDocSync`
|
|
* on the client. Checked here rather than through @RequirePermission: the
|
|
* permission table has no "manage integrations" action and inventing one
|
|
* would grant it to every trip_member by default, which is the opposite of
|
|
* what a credential this broad needs.
|
|
*
|
|
* The 403 still says "owner": an admin never sees it, and to everybody who
|
|
* does, the owner is the person to ask.
|
|
*
|
|
* R2 (Plan 3h Task 5): the trip-owner lookup itself (DSCTRL1, raw SQL
|
|
* directly in this controller — the architecture deviation the whole
|
|
* program's gather flagged) now lives on `DocSyncConfigService
|
|
* .assertCanManage`; this stays a thin delegation so every one of this
|
|
* controller's existing call sites (string `tripId`) is unchanged.
|
|
*/
|
|
private async assertCanManage(tripId: string, user: User): Promise<void> {
|
|
await this.config.assertCanManage(Number(tripId), user);
|
|
}
|
|
|
|
// ── Providers and status ───────────────────────────────────────────────────
|
|
|
|
/**
|
|
* Which providers this instance has switched on, with their form fields.
|
|
* R2: the raw catalog read (DSCTRL2) and its `available`/`fields`
|
|
* composition now live on `DocSyncConfigService.providersCatalog`.
|
|
*/
|
|
@Get('providers')
|
|
async providers() {
|
|
return this.config.providersCatalog();
|
|
}
|
|
|
|
@Get('status')
|
|
status(@Param('tripId') tripId: string) {
|
|
return this.sync.status(Number(tripId));
|
|
}
|
|
|
|
// ── Connections ────────────────────────────────────────────────────────────
|
|
|
|
@Get('connections')
|
|
async listConnections(@Param('tripId') tripId: string) {
|
|
const rows = await this.config.listConnections(Number(tripId));
|
|
return await Promise.all(rows.map((c) => this.config.publicConnection(c)));
|
|
}
|
|
|
|
@Put('connections')
|
|
@HttpCode(200)
|
|
async upsertConnection(
|
|
@Param('tripId') tripId: string,
|
|
@CurrentUser() user: User,
|
|
@Body() body: DocsyncConnectionDto,
|
|
) {
|
|
await this.assertCanManage(tripId, user);
|
|
if (!(await this.config.enabledProviderIds()).includes(body.providerId)) {
|
|
throw new HttpException(`Provider: "${body.providerId}" is not enabled, contact server administrator`, 400);
|
|
}
|
|
const res = await this.config.upsertConnection(Number(tripId), Number(user.id), body);
|
|
if (docFailed(res)) throw new HttpException(res.error.detail || res.error.code, 400);
|
|
return this.config.publicConnection(res.data);
|
|
}
|
|
|
|
/**
|
|
* Probe form values. Always 200: the result is in the body, because this is
|
|
* a form field, not a failure of the request. The photo providers pin the
|
|
* same contract with a test their e2e suite marks CRITICAL.
|
|
*/
|
|
@Post('connections/test')
|
|
@HttpCode(200)
|
|
async testConnection(
|
|
@Param('tripId') tripId: string,
|
|
@CurrentUser() user: User,
|
|
@Body() body: DocsyncConnectionTestDto,
|
|
) {
|
|
await this.assertCanManage(tripId, user);
|
|
const provider = this.registry.get(body.providerId);
|
|
if (!provider) return { connected: false, error: 'unknown_provider' };
|
|
|
|
const urlCheck = await this.config.validateBaseUrl(body.baseUrl);
|
|
if (docFailed(urlCheck)) return { connected: false, error: urlCheck.error.code };
|
|
|
|
// Probing with the values on screen, merged over whatever is stored, so a
|
|
// user testing an unchanged connection does not have to retype the secret.
|
|
const existing = (await this.config.listConnections(Number(tripId))).find((c) => c.provider_id === body.providerId);
|
|
// Only for the address the credential was stored against. Merging it into a
|
|
// probe of an arbitrary baseUrl turns this route into a way to have TREK
|
|
// post a stored API token at a server of the caller's choosing, which is
|
|
// exactly what somebody who inherited a trip but not its credentials would
|
|
// reach for. Same host, same scheme, same port, or the caller types it in.
|
|
const sameTarget = !!existing && sameOrigin(existing.base_url, urlCheck.data.url);
|
|
const stored = sameTarget && existing ? this.config.toRef(existing) : null;
|
|
const fields = await this.config.providerFields(body.providerId);
|
|
const secrets: Record<string, string> = { ...(stored?.secrets ?? {}) };
|
|
const settings: Record<string, string> = { ...(stored?.settings ?? {}) };
|
|
for (const f of fields) {
|
|
const submitted = body.credentials[f.field_key];
|
|
if (submitted === undefined || submitted === '') continue;
|
|
if (f.secret === 1) secrets[f.field_key] = submitted;
|
|
else settings[f.field_key] = submitted;
|
|
}
|
|
|
|
const res = await provider.probe({
|
|
connectionId: existing?.id ?? 0,
|
|
createdAt: existing?.created_at ?? '',
|
|
ownerId: Number(user.id),
|
|
baseUrl: urlCheck.data.url,
|
|
secrets,
|
|
settings,
|
|
allowInsecureTls: body.allowInsecureTls,
|
|
});
|
|
if (docFailed(res)) return { connected: false, error: res.error.code, detail: res.error.detail };
|
|
if (existing) await this.config.recordProbe(existing.id, 'ok', null, res.data.capabilities);
|
|
return { connected: true, account: res.data.account, capabilities: res.data.capabilities };
|
|
}
|
|
|
|
@Delete('connections/:connectionId')
|
|
@HttpCode(200)
|
|
async deleteConnection(
|
|
@Param('tripId') tripId: string,
|
|
@Param('connectionId') connectionId: string,
|
|
@CurrentUser() user: User,
|
|
) {
|
|
await this.assertCanManage(tripId, user);
|
|
const conn = await this.config.getConnection(Number(connectionId));
|
|
if (!conn || conn.trip_id !== Number(tripId)) throw new HttpException('Connection not found', 404);
|
|
// Its bindings go with it (ON DELETE CASCADE), so read them first. Every
|
|
// subscription TREK registered for one of them is taken down while the
|
|
// credential is still here to do it with, as unbinding one does: left
|
|
// standing, a Paperless workflow or a Nextcloud listener keeps posting to
|
|
// a token that answers nothing, for good.
|
|
const unbound = (await this.config.listLinks(conn.trip_id)).filter((l) => l.connection_id === conn.id);
|
|
const provider = this.registry.get(conn.provider_id);
|
|
if (provider?.unregisterWebhook) {
|
|
const ref = this.config.toRef(conn);
|
|
for (const link of unbound) {
|
|
if (link.webhook_subscription_id) await provider.unregisterWebhook(ref, link.webhook_subscription_id);
|
|
}
|
|
}
|
|
await this.config.deleteConnection(conn.id);
|
|
for (const link of unbound) this.announceBinding(link);
|
|
return { success: true };
|
|
}
|
|
|
|
// ── Scopes ─────────────────────────────────────────────────────────────────
|
|
|
|
/** Folders, tags or spaces the trip could be bound to. */
|
|
@Get('connections/:connectionId/scopes')
|
|
async listScopes(
|
|
@Param('tripId') tripId: string,
|
|
@Param('connectionId') connectionId: string,
|
|
@CurrentUser() user: User,
|
|
@Query('q') q?: string,
|
|
) {
|
|
await this.assertCanManage(tripId, user);
|
|
const conn = await this.config.getConnection(Number(connectionId));
|
|
if (!conn || conn.trip_id !== Number(tripId)) throw new HttpException('Connection not found', 404);
|
|
const provider = this.registry.get(conn.provider_id);
|
|
if (!provider) throw new HttpException('Provider not available', 400);
|
|
const res = await provider.listScopes(this.config.toRef(conn), q);
|
|
if (docFailed(res)) return { scopes: [], error: res.error.code };
|
|
return { scopes: res.data };
|
|
}
|
|
|
|
@Post('connections/:connectionId/scopes')
|
|
async createScope(
|
|
@Param('tripId') tripId: string,
|
|
@Param('connectionId') connectionId: string,
|
|
@CurrentUser() user: User,
|
|
@Body() body: DocsyncScopeCreateDto,
|
|
) {
|
|
await this.assertCanManage(tripId, user);
|
|
const conn = await this.config.getConnection(Number(connectionId));
|
|
if (!conn || conn.trip_id !== Number(tripId)) throw new HttpException('Connection not found', 404);
|
|
const provider = this.registry.get(conn.provider_id);
|
|
if (!provider) throw new HttpException('Provider not available', 400);
|
|
const res = await provider.createScope(this.config.toRef(conn), body.name);
|
|
if (docFailed(res)) throw new HttpException(res.error.code, 400);
|
|
return res.data;
|
|
}
|
|
|
|
// ── Bindings ───────────────────────────────────────────────────────────────
|
|
|
|
@Get('links')
|
|
async listLinks(@Param('tripId') tripId: string, @Req() req: Request) {
|
|
const base = publicOrigin(req);
|
|
const rows = await this.config.listLinks(Number(tripId));
|
|
return await Promise.all(rows.map((l) => this.config.publicLink(l, base)));
|
|
}
|
|
|
|
@Post('links')
|
|
@HttpCode(200)
|
|
async createLink(
|
|
@Param('tripId') tripId: string,
|
|
@CurrentUser() user: User,
|
|
@Body() body: DocsyncLinkDto,
|
|
@Req() req: Request,
|
|
) {
|
|
await this.assertCanManage(tripId, user);
|
|
const res = await this.config.createLink(Number(tripId), Number(user.id), body);
|
|
if (docFailed(res)) throw new HttpException(res.error.detail || res.error.code, 400);
|
|
this.announceBinding(res.data);
|
|
|
|
// Subscribe where the provider lets TREK do it itself. A failure here is
|
|
// not a failure of the binding (polling still carries it), so it is logged
|
|
// rather than thrown at the user; the first run that follows would write
|
|
// over anything put into the link state.
|
|
const conn = await this.config.getConnection(res.data.connection_id);
|
|
const provider = conn ? this.registry.get(conn.provider_id) : undefined;
|
|
if (conn && provider?.registerWebhook) {
|
|
const base = publicOrigin(req);
|
|
if (base) {
|
|
const hook = await provider.registerWebhook(
|
|
this.config.toRef(conn),
|
|
this.config.toScopeRef(res.data),
|
|
`${base}/api/docsync/webhook/${res.data.webhook_token}`,
|
|
this.config.webhookSecret(res.data),
|
|
);
|
|
if (docFailed(hook)) {
|
|
this.logger.warn(
|
|
`link ${res.data.id}: ${conn.provider_id} refused the webhook subscription (${hook.error.code}${hook.error.detail ? `: ${hook.error.detail}` : ''}), polling carries it`,
|
|
);
|
|
} else {
|
|
await this.config.setWebhookSubscriptionId(res.data.id, hook.data.subscriptionId);
|
|
}
|
|
}
|
|
}
|
|
|
|
// A first run right away, so the user sees something happen instead of
|
|
// waiting out a poll interval and wondering whether it worked.
|
|
//
|
|
// L1 (Plan 3h Task 7 review) — a third R9-class detached chain the
|
|
// inventory missed: `syncLink` runs ~36 ORM/Kysely statements, detached
|
|
// after this response goes out, on the request's own EntityManager fork.
|
|
// Wrapped in its own `withRequestContext` fork for the same reason the
|
|
// webhook nudge timer (`DocSyncWebhookController#schedule`) and the
|
|
// import-job runner (`ImportJobsService#start`) are: insurance against
|
|
// the request-scoped fork being gone by the time this runs, per 3f's own
|
|
// measurement that `AsyncLocalStorage` survives a detached chain intact
|
|
// in this codebase today, not a fix for an observed failure. A failure
|
|
// here is not a failure of the binding (the next poll carries it), so it
|
|
// is logged rather than thrown — same posture as the webhook
|
|
// subscription failure just above.
|
|
void withRequestContext(this.orm, () => this.sync.syncLink(res.data, { full: true })).catch((err: unknown) => {
|
|
this.logger.error(
|
|
`link ${res.data.id}: the first run after creation failed (${err instanceof Error ? err.message : String(err)}), the next poll carries it`,
|
|
);
|
|
});
|
|
return await this.config.publicLink((await this.config.getLink(res.data.id)) ?? res.data, publicOrigin(req));
|
|
}
|
|
|
|
@Patch('links/:linkId')
|
|
@HttpCode(200)
|
|
async updateLink(
|
|
@Param('tripId') tripId: string,
|
|
@Param('linkId') linkId: string,
|
|
@CurrentUser() user: User,
|
|
@Body() body: DocsyncLinkUpdateDto,
|
|
@Req() req: Request,
|
|
) {
|
|
await this.assertCanManage(tripId, user);
|
|
const link = await this.config.getLink(Number(linkId));
|
|
if (!link || link.trip_id !== Number(tripId)) throw new HttpException('Link not found', 404);
|
|
const updated = await this.config.updateLink(link.id, body);
|
|
return await this.config.publicLink(updated ?? link, publicOrigin(req));
|
|
}
|
|
|
|
@Delete('links/:linkId')
|
|
@HttpCode(200)
|
|
async deleteLink(@Param('tripId') tripId: string, @Param('linkId') linkId: string, @CurrentUser() user: User) {
|
|
await this.assertCanManage(tripId, user);
|
|
const link = await this.config.getLink(Number(linkId));
|
|
if (!link || link.trip_id !== Number(tripId)) throw new HttpException('Link not found', 404);
|
|
|
|
const conn = await this.config.getConnection(link.connection_id);
|
|
const provider = conn ? this.registry.get(conn.provider_id) : undefined;
|
|
if (conn && provider?.unregisterWebhook && link.webhook_subscription_id) {
|
|
await provider.unregisterWebhook(this.config.toRef(conn), link.webhook_subscription_id);
|
|
}
|
|
await this.config.deleteLink(link.id);
|
|
this.announceBinding(link);
|
|
// Unbinding keeps both copies. Nothing is deleted anywhere.
|
|
return { success: true, documentsKept: true };
|
|
}
|
|
|
|
@Post('links/:linkId/sync')
|
|
@HttpCode(200)
|
|
async syncNow(@Param('tripId') tripId: string, @Param('linkId') linkId: string, @Body() body: DocsyncSyncNowDto) {
|
|
const link = await this.config.getLink(Number(linkId));
|
|
if (!link || link.trip_id !== Number(tripId)) throw new HttpException('Link not found', 404);
|
|
// An orphaned binding stays orphaned: its credential belongs to somebody who
|
|
// is no longer on this trip. The run itself would stand down as well; this
|
|
// says why, instead of answering with an empty run.
|
|
if (await this.config.isOrphaned(link)) {
|
|
throw new HttpException({ error: 'This binding lost its owner and has to be reconnected' }, 409);
|
|
}
|
|
// Refused before the shelved rows are touched, so a binding an admin
|
|
// switched off stays exactly as it was and resumes where it stopped. A code
|
|
// rather than a sentence: the client says it in the reader's language.
|
|
if (await this.sync.isSwitchedOff(link)) {
|
|
throw new HttpException({ error: PROVIDER_DISABLED }, 409);
|
|
}
|
|
// A person asking for a run is also asking for the rows that gave up to be
|
|
// tried once more; the scheduler gets no such reprieve.
|
|
await this.sync.retryShelvedItems(link.id);
|
|
return this.sync.syncLink(link, { full: body.full });
|
|
}
|
|
|
|
// ── Documents and conflicts ────────────────────────────────────────────────
|
|
|
|
/**
|
|
* R2: DSCTRL4/DSCTRL5's two near-duplicate listing statements now live on
|
|
* `DocSyncService.itemsForTrip`, kept as two distinct repository methods
|
|
* (state-filtered vs unfiltered) — never unified with `issues()`'s own
|
|
* `LIMIT 200` fixed-state-list read.
|
|
*/
|
|
@Get('items')
|
|
async items(@Param('tripId') tripId: string, @Query('state') state?: string) {
|
|
return this.sync.itemsForTrip(Number(tripId), state);
|
|
}
|
|
|
|
@Post('items/:itemId/resolve')
|
|
@HttpCode(200)
|
|
async resolve(
|
|
@Param('tripId') tripId: string,
|
|
@Param('itemId') itemId: string,
|
|
@CurrentUser() user: User,
|
|
@Body() body: DocsyncResolveConflictDto,
|
|
) {
|
|
await this.assertCanManage(tripId, user);
|
|
const ok = await this.sync.resolveConflict(Number(itemId), body.keep, Number(tripId));
|
|
if (!ok) throw new HttpException('Item is not in conflict', 400);
|
|
return { success: true };
|
|
}
|
|
}
|
|
|
|
/**
|
|
* The origin a provider has to call back on.
|
|
*
|
|
* Derived from the request rather than from configuration because a self-hosted
|
|
* TREK is reached under whatever name its operator chose, and asking them to
|
|
* maintain a second copy of it would get it wrong. Returns null behind a proxy
|
|
* that strips the host, in which case the webhook is simply not offered and
|
|
* polling carries the binding.
|
|
*/
|
|
function publicOrigin(req: Request): string | null {
|
|
const host = req.get('x-forwarded-host') || req.get('host');
|
|
if (!host) return null;
|
|
const proto = (req.get('x-forwarded-proto') || req.protocol || 'http').split(',')[0].trim();
|
|
return `${proto}://${host}`;
|
|
}
|