@volter/twin-linkedin 0.1.0

package/src/linkedin-server.ts

@@ -0,0 +1,150 @@
+// LinkedIn twin HTTP server.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler` — manifest door, body read, header map,
+// worldNow() stamp, JSON reply); this file contributes only VALUES — plus the two places LinkedIn's
+// wire exceeds that adapter's text-in/JSON-out shape, both about media BYTES:
+//
+//   - the upload PUTs to the signed `/dms-uploads/…` URLs carry raw bytes, which the adapter's
+//     `request.text()` would corrupt, so they are read here and handed to the same handler as `bytes`;
+//   - the asset bytes themselves, read from the blob seam by digest at LinkedIn's own path shapes —
+//     media.licdn.com's `/dms/image/<asset>/<rendition>/0/<digest>` for an image or a video's
+//     thumbnail, dms.licdn.com's `/playlist/<asset>/<rendition>/0/<digest>` for a video file — with
+//     HTTP Range (206), so a <video> can seek, through the kernel's ranged reads. Those URLs are public at LinkedIn (a feed's <img> and
+//     <video> carry no bearer), so these routes are too.
+import { handleLinkedinTwinRequest } from './linkedin-twin.ts';
+import { assetAsOf, blobKey, readAsset as readStoredAsset, videoPosterSvg, type AssetRecord } from './linkedin-media.ts';
+import { createTwinFetchFromHandler, readResourceBlobRange, resourceBlobSize, runWithCorrelationId, serveHttp, statefulTwinManifest, twinPublicBase, worldNow } from '@volter/world-core';
+
+const SERVICE = 'linkedin';
+
+export interface LinkedinTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+}
+
+const UPLOAD_PATH = /^\/dms-uploads\//;
+const IMAGE_BYTES = /^\/dms\/image\/([A-Za-z0-9_-]{8,40})\/(image-shrink_1280|ads-video-thumbnail_720_1280)\/0\/([0-9a-f]{64}|system)$/;
+const VIDEO_BYTES = /^\/playlist\/([A-Za-z0-9_-]{8,40})\/mp4-\d+p-30fp-crf28\/0\/([0-9a-f]{64})$/;
+
+/** The most one read of the blob seam returns: an open-ended `bytes=N-` is answered with at most
+ *  this much (a player asks again from where it stands), and any longer answer — a whole file, a long
+ *  closed or suffix range — is streamed in reads of this size, so no request holds a large file. */
+const RANGE_CAP = 8 * 1024 * 1024;
+
+/** [start, end] of a stored digest as a body: one read when it fits the cap, else a stream of capped reads. */
+async function rangeBody(key: string, start: number, end: number, root?: string): Promise<Blob | ReadableStream<Uint8Array> | null> {
+  if (end - start + 1 <= RANGE_CAP) {
+    const bytes = await readResourceBlobRange(SERVICE, key, start, end, root);
+    return bytes === null ? null : new Blob([new Uint8Array(bytes)]);
+  }
+  let at = start;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      if (at > end) { controller.close(); return; }
+      const chunk = await readResourceBlobRange(SERVICE, key, at, Math.min(end, at + RANGE_CAP - 1), root);
+      if (chunk === null || chunk.length === 0) { controller.error(new Error('the stored bytes went away mid-read')); return; }
+      at += chunk.length;
+      controller.enqueue(new Uint8Array(chunk));
+    },
+  });
+}
+
+/**
+ * A stored digest as a response, read through the kernel's ranged reads (which walk the branch's
+ * ancestors), honouring a single `Range: bytes=` (206 / 416) as a CDN does.
+ */
+async function bytesResponse(request: Request, sha256: string, contentType: string, root?: string): Promise<Response> {
+  const key = blobKey(sha256);
+  const total = await resourceBlobSize(SERVICE, key, root);
+  if (total === null) return notFound();
+  const base = { 'content-type': contentType, 'accept-ranges': 'bytes', 'cache-control': 'public, max-age=604800, immutable' };
+  let start = 0;
+  let end = total - 1;
+  const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
+  if (range && (range[1] !== '' || range[2] !== '')) {
+    if (range[1] === '') { start = Math.max(0, total - Number(range[2])); } else {
+      start = Number(range[1]);
+      end = range[2] === '' ? Math.min(total - 1, start + RANGE_CAP - 1) : Math.min(Number(range[2]), total - 1);
+    }
+    if (start >= total || start > end) return new Response(null, { status: 416, headers: { ...base, 'content-range': `bytes */${total}` } });
+  }
+  const partial = start !== 0 || end !== total - 1;
+  const headers = { ...base, 'content-length': String(end - start + 1), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) };
+  if (request.method === 'HEAD') return new Response(null, { status: partial ? 206 : 200, headers });
+  const body = await rangeBody(key, start, end, root);
+  if (body === null) return notFound();
+  return new Response(body, { status: partial ? 206 : 200, headers });
+}
+
+/** An asset as it stands at the world's instant (a finalized video becomes AVAILABLE with time). */
+async function readAsset(id: string, root?: string): Promise<AssetRecord | undefined> {
+  const stored = await readStoredAsset(id, root);
+  return stored ? assetAsOf(stored, Date.parse(worldNow())) : undefined;
+}
+
+const notFound = (): Response => Response.json({ status: 404, code: 'NOT_FOUND', message: 'Not Found' }, { status: 404 });
+
+export function createLinkedinTwinFetch(options: LinkedinTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const adapted = createTwinFetchFromHandler(handleLinkedinTwinRequest, {
+    ...options,
+    extras: (request) => ({ publicBase: twinPublicBase(request) }),
+    manifest: statefulTwinManifest({ vendor: 'linkedin', twinOf: 'the LinkedIn Community Management API (organization posts, images, videos)', stores: 'organizations, admin roles, posts, and uploaded images and videos' }),
+  });
+  const serve = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const reading = request.method === 'GET' || request.method === 'HEAD';
+    const image = reading ? IMAGE_BYTES.exec(url.pathname) : null;
+    if (image) {
+      const asset = await readAsset(image[1]!, options.root);
+      if (!asset || asset.status !== 'AVAILABLE') return notFound();
+      const thumbnail = image[2] === 'ads-video-thumbnail_720_1280';
+      if (thumbnail && asset.kind !== 'video') return notFound();
+      if (thumbnail && image[3] === 'system') {
+        if (asset.thumbnail_sha256) return notFound();
+        return new Response(request.method === 'HEAD' ? null : videoPosterSvg(asset.width ?? 0, asset.height ?? 0), { headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=604800' } });
+      }
+      const sha = thumbnail ? asset.thumbnail_sha256 : asset.kind === 'image' ? asset.sha256 : undefined;
+      if (!sha || sha !== image[3]) return notFound();
+      return bytesResponse(request, sha, (thumbnail ? asset.thumbnail_media_type : asset.media_type) ?? 'application/octet-stream', options.root);
+    }
+    const video = reading ? VIDEO_BYTES.exec(url.pathname) : null;
+    if (video) {
+      const asset = await readAsset(video[1]!, options.root);
+      if (!asset || asset.kind !== 'video' || asset.status !== 'AVAILABLE' || asset.sha256 !== video[2]) return notFound();
+      return bytesResponse(request, asset.sha256, 'video/mp4', options.root);
+    }
+    if (request.method === 'PUT' && UPLOAD_PATH.test(url.pathname)) {
+      const bytes = new Uint8Array(await request.arrayBuffer());
+      const headers: Record<string, string> = {};
+      request.headers.forEach((value, key) => { headers[key] = value; });
+      const invoke = () => handleLinkedinTwinRequest({
+        method: request.method,
+        path: url.pathname + (url.search || ''),
+        headers,
+        bytes,
+        readOnly: options.readOnly ?? false,
+        occurredAt: worldNow(),
+        publicBase: twinPublicBase(request),
+        ...(options.root !== undefined ? { root: options.root } : {}),
+      });
+      const requestId = request.headers.get('x-twins-request-id') ?? undefined;
+      const result = await (requestId ? runWithCorrelationId(requestId, invoke) : invoke());
+      const empty = result.body === null || result.body === undefined || result.body === '';
+      return new Response(empty ? null : JSON.stringify(result.body), { status: result.status, headers: { ...(empty ? {} : { 'content-type': 'application/json' }), ...result.headers } });
+    }
+    return adapted(request);
+  };
+  // every answer carries the World's instant as its HTTP Date (an HTTP server's own header), so a
+  // client — the mirror's relative times — reads the World's now rather than its own clock
+  return async (request: Request): Promise<Response> => {
+    const res = await serve(request);
+    const headers = new Headers(res.headers);
+    headers.set('date', new Date(worldNow()).toUTCString());
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+  };
+}
+
+export async function createLinkedinTwinServer(options: { root?: string; port?: number; readOnly?: boolean } = {}) {
+  return serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createLinkedinTwinFetch(options) });
+}