@volter/twin-instagram 0.1.0

package/src/instagram-server.ts

@@ -0,0 +1,146 @@
+// Instagram 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 Instagram's
+// wire exceeds that adapter's text-in/JSON-out shape, both about media BYTES:
+//
+//   - the rupload POSTs (rupload.facebook.com/ig-api-upload/…) carry raw video bytes, which the
+//     adapter's `request.text()` would corrupt, so they are read here and handed to the same handler
+//     as `bytes`;
+//   - the bytes themselves, read from the blob seam by digest at the CDN's path shapes — a Reel's
+//     `media_url` (`/o1/v/t16/f2/m86/<digest>.mp4`), its stand-in thumbnail
+//     (`/v/t51.71878-15/<digest>_poster.svg`) and a profile picture (`/v/t51.2885-19/<digest>.jpg|png`)
+//     — with HTTP Range (206/416), so a <video> can seek, through the kernel's ranged reads. Those URLs
+//     are public at Instagram's CDN (a page's <video> carries no token), so these routes are too, and
+//     they serve only a digest a held media or profile names.
+import { handleInstagramTwinRequest } from './instagram-twin.ts';
+import { blobKey, reelPosterSvg } from './instagram-media.ts';
+import { createTwinFetchFromHandler, ownFields, projectResources, readResourceBlobRange, resourceBlobSize, runWithCorrelationId, serveHttp, statefulTwinManifest, twinPublicBase, worldNow } from '@volter/world-core';
+
+const SERVICE = 'instagram';
+
+export interface InstagramTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+}
+
+const RUPLOAD_PATH = /^\/ig-api-upload\//;
+const REEL_BYTES = /^\/o1\/v\/t16\/f2\/m86\/([0-9a-f]{64})\.mp4$/;
+const REEL_POSTER = /^\/v\/t51\.71878-15\/([0-9a-f]{64})_poster\.svg$/;
+const PROFILE_PICTURE = /^\/v\/t51\.2885-19\/([0-9a-f]{64})\.(jpg|png)$/;
+
+/** 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. */
+export const RANGE_CAP = 8 * 1024 * 1024;
+
+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, 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 });
+}
+
+const notFound = (): Response => new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+
+type Row = Record<string, any>;
+/** The live media whose Reel is this digest, if any. */
+function mediaWithVideo(sha256: string, root?: string): Row | undefined {
+  return (projectResources(SERVICE, root) as unknown as Row[]).map((r) => ({ r, f: ownFields(r as never) as Row }))
+    .find(({ r, f }) => r.type === 'media' && f._deleted !== true && f.deleted !== true && f._video?.sha256 === sha256)?.f;
+}
+function userWithPicture(sha256: string, root?: string): Row | undefined {
+  return (projectResources(SERVICE, root) as unknown as Row[]).map((r) => ({ r, f: ownFields(r as never) as Row }))
+    .find(({ r, f }) => r.type === 'ig_user' && f._profile_picture?.sha256 === sha256)?.f;
+}
+
+export function createInstagramTwinFetch(options: InstagramTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const adapted = createTwinFetchFromHandler(handleInstagramTwinRequest, {
+    ...options,
+    extras: (request) => ({ publicBase: twinPublicBase(request) }),
+    manifest: statefulTwinManifest({ vendor: 'instagram', twinOf: 'the Instagram Platform content publishing API (Reels, resumable upload)', stores: 'professional accounts, published Reels, and staged media containers' }),
+  });
+  const serve = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const reading = request.method === 'GET' || request.method === 'HEAD';
+    const reel = reading ? REEL_BYTES.exec(url.pathname) : null;
+    if (reel) return mediaWithVideo(reel[1]!, options.root) ? bytesResponse(request, reel[1]!, 'video/mp4', options.root) : notFound();
+    const poster = reading ? REEL_POSTER.exec(url.pathname) : null;
+    if (poster) {
+      const media = mediaWithVideo(poster[1]!, options.root);
+      if (!media) return notFound();
+      return new Response(request.method === 'HEAD' ? null : reelPosterSvg(Number(media._video.width ?? 0), Number(media._video.height ?? 0)), { headers: { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=604800' } });
+    }
+    const picture = reading ? PROFILE_PICTURE.exec(url.pathname) : null;
+    if (picture) {
+      const user = userWithPicture(picture[1]!, options.root);
+      return user ? bytesResponse(request, picture[1]!, String(user._profile_picture.media_type), options.root) : notFound();
+    }
+    if ((request.method === 'POST' || request.method === 'GET') && RUPLOAD_PATH.test(url.pathname)) {
+      const bytes = request.method === 'POST' ? new Uint8Array(await request.arrayBuffer()) : undefined;
+      const headers: Record<string, string> = {};
+      request.headers.forEach((value, key) => { headers[key] = value; });
+      const invoke = () => handleInstagramTwinRequest({
+        method: request.method,
+        path: url.pathname + (url.search || ''),
+        headers,
+        ...(bytes ? { 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());
+      return new Response(JSON.stringify(result.body), { status: result.status, headers: { 'content-type': 'application/json; charset=UTF-8', ...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 createInstagramTwinServer(options: { root?: string; port?: number; readOnly?: boolean } = {}) {
+  return serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createInstagramTwinFetch(options) });
+}