Skip to content

Open source CapCut alternative.

TypeScript
8.5 KB
Raw Blame
"use client";

/**
 * Note edits are saved in this browser first and synced to the cloud after.
 *
 * Every edit lands in localStorage at once, synchronously, stamped with the
 * moment it was made. A flush sends what is pending, and an entry leaves the
 * outbox only once the server has answered for it. A failed send stays
 * pending and is retried with backoff; the page also flushes when it comes
 * back online, when the session confirms its account, and as a keepalive
 * request when it is hidden (useNoteOutboxSync). Anything those miss syncs
 * the next time the notes are listed.
 *
 * The stamp is the edit's own, so a write that syncs late still loses to a
 * newer edit from the phone: the server keeps whichever stamp is newer.
 * Entries are kept per account and sent only for the confirmed account, so
 * two people sharing a browser never write each other's notes. A process with
 * no account bound — the cloud worker, whose transport carries the user —
 * keeps no outbox: its writes go straight to the server and fail when the
 * server does.
 */

import { confirmedEngineUser, currentEngineUser } from "./api";
import type { NoteLocation } from "./noteReference";
import { backendFor } from "./residency";
import type { CutNote } from "./notes";
import { UserError } from "./userError";

/** One note as a write sends it. */
export interface NoteWrite {
  libraryLocation?: NoteLocation | null;
  id: string;
  title: string;
  body: string;
  colorIndex: number;
  folderId: string | null;
  labelIds: string[];
}

interface Pending {
  note: NoteWrite;
  updatedAt: number;
}

/** How a send goes out: "unloading" rides a keepalive request so it can
 * outlive a closing page. */
export type SendMode = "now" | "unloading";

const OUTBOX_PREFIX = "cut:note-outbox:";

/** Waits between retries of a send the server did not take, longest last. */
const RETRY_MS = [2_000, 10_000, 30_000, 120_000];

/** A keepalive request carries at most 64 KB. */
const KEEPALIVE_MAX_BYTES = 60_000;

// Answers that mean the write may land later: signed out, a timeout, a rate
// limit, or the server failing. Any other refusal is the write itself.
const HTTP_UNAUTHORIZED = 401;
const HTTP_TIMEOUT = 408;
const HTTP_TOO_MANY = 429;
const HTTP_SERVER_ERROR = 500;
const retryable = (status: number) =>
  status === HTTP_UNAUTHORIZED || status === HTTP_TIMEOUT || status === HTTP_TOO_MANY || status >= HTTP_SERVER_ERROR;

// One key per note, so a keystroke rewrites only the note being typed.
const keyOf = (account: string, id: string) => `${OUTBOX_PREFIX}${account}:${id}`;

// Entries whose storage write failed — storage full or blocked — held for
// this session. A held entry is newer than whatever storage still has.
const memory = new Map<string, Pending>();

function readPending(account: string, id: string): Pending | undefined {
  const key = keyOf(account, id);
  const held = memory.get(key);
  if (held) {
    return held;
  }
  try {
    const raw = localStorage.getItem(key);
    return raw ? (JSON.parse(raw) as Pending) : undefined;
  } catch {
    return undefined;
  }
}

function writePending(account: string, id: string, pending: Pending | null): void {
  const key = keyOf(account, id);
  memory.delete(key);
  try {
    if (pending) {
      localStorage.setItem(key, JSON.stringify(pending));
    } else {
      localStorage.removeItem(key);
    }
  } catch {
    if (pending) {
      memory.set(key, pending);
    }
  }
}

function pendingIds(account: string): string[] {
  const prefix = `${OUTBOX_PREFIX}${account}:`;
  const keys = new Set([...memory.keys()].filter((k) => k.startsWith(prefix)));
  try {
    for (let i = 0; i < localStorage.length; i++) {
      const key = localStorage.key(i);
      if (key?.startsWith(prefix)) {
        keys.add(key);
      }
    }
  } catch {
    // Blocked storage lists the held entries alone.
  }
  return [...keys].map((k) => k.slice(prefix.length));
}

/** A pending write as the list shows it until the server answers. */
const localNote = (p: Pending, over?: CutNote): CutNote => ({
  libraryLocation: over?.libraryLocation ?? null,
  ...p.note,
  updatedAt: p.updatedAt,
  deletedAt: null,
  createdAt: over?.createdAt ?? p.updatedAt,
});

/** Save a note's current content in this browser, stamped now. False when no
 * account is bound, so there is no outbox to hold it. */
export function stageNote(note: NoteWrite): boolean {
  const account = currentEngineUser();
  if (!account) {
    return false;
  }
  writePending(account, note.id, { note, updatedAt: Date.now() });
  return true;
}

/** Forget a note's pending write: the note was deleted. */
export function dropPendingNote(id: string): void {
  const account = currentEngineUser();
  if (account) {
    writePending(account, id, null);
  }
}

/** The server's list with this browser's pending writes laid over it. A
 * pending write the server already holds, or holds something newer than,
 * leaves the outbox here. */
export function withPendingNotes(serverNotes: CutNote[]): CutNote[] {
  const account = currentEngineUser();
  const ids = account ? pendingIds(account) : [];
  if (!account || ids.length === 0) {
    return serverNotes;
  }

  // Lay each pending write over the server's copy, or drop it when the
  // server's copy is as new: e.g. an edit sent by keepalive as the tab closed.
  const byId = new Map(serverNotes.map((n) => [n.id, n]));
  let left = 0;
  for (const id of ids) {
    const pending = readPending(account, id);
    if (!pending) {
      continue;
    }
    const server = byId.get(id);
    if (server && server.updatedAt >= pending.updatedAt) {
      writePending(account, id, null);
      continue;
    }
    byId.set(id, localNote(pending, server));
    left++;
  }
  if (left > 0) {
    void flushNoteOutbox();
  }
  return [...byId.values()].sort((a, b) => b.updatedAt - a.updatedAt);
}

type Sent = { kind: "landed"; note: CutNote } | { kind: "held" } | { kind: "refused" };

async function send(note: NoteWrite, updatedAt: number, mode: SendMode): Promise<Sent> {
  const body = JSON.stringify({ ...note, updatedAt });
  const res = await backendFor("cloud")
    .fetch(`/api/cut/notes/${encodeURIComponent(note.id)}`, {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body,
      keepalive: mode === "unloading" && body.length < KEEPALIVE_MAX_BYTES,
    })
    .catch(() => null);
  if (!res) {
    return { kind: "held" };
  }
  if (res.ok) {
    return { kind: "landed", note: (await res.json()) as CutNote };
  }
  return retryable(res.status) ? { kind: "held" } : { kind: "refused" };
}

/** Write a note with no outbox behind it: the server's answer, or an error. */
export async function sendNoteNow(note: NoteWrite): Promise<CutNote> {
  const sent = await send(note, Date.now(), "now");
  if (sent.kind !== "landed") {
    throw new UserError("note_save_failed", "Could not save the note.");
  }
  return sent.note;
}

/** Send one note's pending write. Answers with the version the server kept,
 * or with the pending write itself while it waits to sync. A write the server
 * refuses outright leaves the outbox and throws. */
export async function flushNote(id: string, mode: SendMode = "now"): Promise<CutNote | null> {
  const account = currentEngineUser();
  const pending = account ? readPending(account, id) : undefined;
  if (!account || !pending) {
    return null;
  }
  // Sent once the live session confirms this is still the account signed in.
  if (account !== confirmedEngineUser()) {
    return localNote(pending);
  }

  const sent = await send(pending.note, pending.updatedAt, mode);
  if (sent.kind === "held") {
    scheduleRetry();
    return localNote(pending);
  }

  // Off the outbox only if no newer edit was staged while this one was out.
  if (readPending(account, id)?.updatedAt === pending.updatedAt) {
    writePending(account, id, null);
  }
  if (sent.kind === "refused") {
    throw new UserError("note_save_failed", "Could not save the note.");
  }
  retryStep = 0;
  return sent.note;
}

/** Send every pending write for the signed-in account. */
export async function flushNoteOutbox(mode: SendMode = "now"): Promise<void> {
  const account = confirmedEngineUser();
  if (!account) {
    return;
  }
  await Promise.all(pendingIds(account).map((id) => flushNote(id, mode).catch(() => null)));
}

let retryTimer: ReturnType<typeof setTimeout> | null = null;
let retryStep = 0;

function scheduleRetry(): void {
  if (retryTimer) {
    return;
  }
  const wait = RETRY_MS[Math.min(retryStep, RETRY_MS.length - 1)];
  retryStep++;
  retryTimer = setTimeout(() => {
    retryTimer = null;
    void flushNoteOutbox();
  }, wait);
}