@deckbuilderkit/view-rest 0.0.0-stage → 0.1.0

package/src/rest/tabs-store.ts

@@ -0,0 +1,262 @@
+import { useEffect, useSyncExternalStore } from 'react';
+import { draftToSpec, emptyDraft, type HttpRequestDraft } from '@deckbuilderkit/editor';
+import type { HttpResponseInfo } from '@deckbuilderkit/server-core/protocol';
+import { type ApiError, errorOf } from '@deckbuilderkit/ui';
+import { restApi as api } from '../client';
+import type { RestTabsFile, SavedRequest } from '../settings';
+
+
+/** A REST tab as the tabs store keeps it (no Authorization value). */
+export interface RestTab {
+  id: string;
+  draft: HttpRequestDraft;
+  savedId?: string;
+  /** Saved request's name, or an imported request's name. */
+  title?: string;
+}
+
+/** Per-tab state that lives only for the app's lifetime. */
+export interface TabRuntime {
+  auth: string;
+  /** Set when the tab came from an import or `openRestTab`; `auth` tells the auth field to accept a value. */
+  imported?: { name: string; auth: boolean };
+  response?: HttpResponseInfo;
+  error?: ApiError;
+  sending: boolean;
+  savedPath?: string;
+}
+
+interface Snapshot {
+  tabs: RestTab[];
+  active: string;
+  runtime: Record<string, TabRuntime>;
+  /** The last open attempt found every tab with unsaved work at the cap. */
+  full?: boolean;
+}
+
+/** Saved requests as the REST screen last loaded them; until known, a tab with a saved id counts as dirty. */
+let savedList: SavedRequest[] | undefined;
+
+const MAX_TABS = 30;
+const SAVE_DELAY_MS = 500;
+/** The server refuses bodies over 1 MB; large drafts lose their body in the stored copy first. */
+const MAX_FILE_CHARS = 950_000;
+
+const newId = () => crypto.randomUUID();
+const blankRuntime = (): TabRuntime => ({ auth: '', sending: false });
+const freshTab = (): RestTab => ({ id: newId(), draft: emptyDraft() });
+
+let snap: Snapshot = (() => {
+  const tab = freshTab();
+  return { tabs: [tab], active: tab.id, runtime: {} };
+})();
+let loaded = false;
+let loading: Promise<void> | undefined;
+/** Tabs opened before the stored ones arrived; they are kept after the stored ones. */
+let touched = false;
+let saveTimer: ReturnType<typeof setTimeout> | undefined;
+const controllers = new Map<string, AbortController>();
+const listeners = new Set<() => void>();
+
+const emit = () => listeners.forEach((l) => l());
+
+function set(next: Partial<Snapshot>, persist = true) {
+  snap = { ...snap, ...next };
+  if (persist) {
+    touched = true;
+    scheduleSave();
+  }
+  emit();
+}
+
+function fileOf(): RestTabsFile {
+  const tabs = snap.tabs.map((t) => ({ ...t, draft: { ...t.draft } }));
+  let size = JSON.stringify(tabs).length;
+  for (const tab of [...tabs].sort((a, b) => b.draft.body.length - a.draft.body.length)) {
+    if (size <= MAX_FILE_CHARS) break;
+    size -= tab.draft.body.length;
+    tab.draft.body = '';
+  }
+  return { version: 1, tabs, active: snap.active };
+}
+
+function scheduleSave() {
+  if (!loaded) return;
+  clearTimeout(saveTimer);
+  saveTimer = setTimeout(() => void api.saveRestTabs(fileOf()).catch(() => {}), SAVE_DELAY_MS);
+}
+
+function ensureLoaded() {
+  loading ??= api
+    .restTabs()
+    .catch(() => undefined)
+    .then((file) => {
+      const stored = file?.tabs ?? [];
+      loaded = true;
+      if (!stored.length) {
+        if (touched) scheduleSave();
+        return;
+      }
+      if (!touched) {
+        const active = stored.some((t) => t.id === file?.active) ? file!.active! : stored[0]!.id;
+        set({ tabs: stored.slice(0, MAX_TABS), active }, false);
+        return;
+      }
+      const ids = new Set(snap.tabs.map((t) => t.id));
+      const blank = (t: RestTab) => !t.savedId && !t.title && !isNonEmpty(t.draft);
+      const opened = snap.tabs.filter((t) => !blank(t) || t.id === snap.active);
+      const merged = [...stored.filter((t) => !ids.has(t.id)), ...opened];
+      while (merged.length > MAX_TABS) {
+        const clean = merged.findIndex((t) => t.id !== snap.active && !dirtyNow(t));
+        merged.splice(clean < 0 ? 0 : clean, 1);
+      }
+      set({ tabs: merged });
+    });
+  return loading;
+}
+
+const sameDraft = (a: HttpRequestDraft, b: HttpRequestDraft) => JSON.stringify(a) === JSON.stringify(b);
+const isNonEmpty = (draft: HttpRequestDraft) => !sameDraft(draft, emptyDraft());
+
+/** Whether `tab` differs from its saved request, or is unsaved and not empty. */
+export function isDirty(tab: RestTab, saved: SavedRequest[] | undefined): boolean {
+  if (!tab.savedId) return isNonEmpty(tab.draft);
+  const record = saved?.find((r) => r.id === tab.savedId);
+  return record ? !sameDraft(tab.draft, record.request) : false;
+}
+
+export const runtimeOf = (id: string): TabRuntime => snap.runtime[id] ?? blankRuntime();
+
+function setRuntime(id: string, patch: Partial<TabRuntime>) {
+  set({ runtime: { ...snap.runtime, [id]: { ...runtimeOf(id), ...patch } } }, false);
+}
+
+const dirtyNow = (tab: RestTab) => (tab.savedId && !savedList ? true : isDirty(tab, savedList));
+
+/** Adds `tab` as the active one; at the cap the oldest clean, inactive tab goes. False when every tab has unsaved work. */
+function append(tab: RestTab, runtime?: Partial<TabRuntime>): boolean {
+  void ensureLoaded();
+  let tabs = snap.tabs;
+  if (tabs.length >= MAX_TABS) {
+    const drop = tabs.find((t) => t.id !== snap.active && !dirtyNow(t) && !runtimeOf(t.id).sending);
+    if (!drop) {
+      set({ full: true }, false);
+      return false;
+    }
+    controllers.get(drop.id)?.abort();
+    controllers.delete(drop.id);
+    tabs = tabs.filter((t) => t.id !== drop.id);
+  }
+  tabs = [...tabs, tab];
+  const keep = new Set(tabs.map((t) => t.id));
+  const rt = Object.fromEntries(Object.entries(snap.runtime).filter(([id]) => keep.has(id)));
+  if (runtime) rt[tab.id] = { ...blankRuntime(), ...runtime };
+  set({ tabs, active: tab.id, runtime: rt, full: false });
+  return true;
+}
+
+/**
+ * Opens `draft` in a new unsaved REST tab and makes it active; `auth` stays in memory only.
+ * Works whether the REST screen is shown or not; the caller then shows it (`go('rest')`).
+ */
+export function openRestTab(draft: HttpRequestDraft, auth?: string, name?: string): string | null {
+  const id = newId();
+  const added = append({ id, draft, ...(name ? { title: name } : {}) }, { auth: auth ?? '', imported: { name: name ?? '', auth: auth !== undefined } });
+  return added ? id : null;
+}
+
+export const restTabs = {
+  /** The REST screen passes its saved list so the cap knows which tabs are clean. */
+  setSaved(list: SavedRequest[] | undefined) {
+    savedList = list;
+  },
+  dismissFull() {
+    if (snap.full) set({ full: false }, false);
+  },
+  newTab() {
+    append(freshTab());
+  },
+  /** Focuses the tab of saved request `item`, or opens one. */
+  openSaved(item: SavedRequest) {
+    const tab = snap.tabs.find((t) => t.savedId === item.id);
+    if (tab) set({ active: tab.id });
+    else append({ id: newId(), draft: item.request, savedId: item.id, title: item.name });
+  },
+  activate(id: string) {
+    if (snap.tabs.some((t) => t.id === id)) set({ active: id });
+  },
+  close(id: string) {
+    const index = snap.tabs.findIndex((t) => t.id === id);
+    if (index < 0) return;
+    controllers.get(id)?.abort();
+    controllers.delete(id);
+    let tabs = snap.tabs.filter((t) => t.id !== id);
+    if (!tabs.length) tabs = [freshTab()];
+    const active = snap.active === id ? tabs[Math.min(index, tabs.length - 1)]!.id : snap.active;
+    const { [id]: _, ...runtime } = snap.runtime;
+    set({ tabs, active, runtime, full: false });
+  },
+  update(id: string, patch: Partial<Omit<RestTab, 'id'>>) {
+    set({ tabs: snap.tabs.map((t) => (t.id === id ? { ...t, ...patch } : t)) });
+  },
+  /** Replaces tab `id`'s content with an imported request. */
+  loadImported(id: string, draft: HttpRequestDraft, name: string, auth?: string) {
+    set({ tabs: snap.tabs.map((t) => (t.id === id ? { id, draft, ...(name ? { title: name } : {}) } : t)) });
+    setRuntime(id, { auth: auth ?? '', imported: { name, auth: auth !== undefined }, response: undefined, error: undefined });
+  },
+  /** Marks tab `id` as showing saved `record`; its Authorization value now lives in the secret store. */
+  markSaved(id: string, record: SavedRequest) {
+    set({ tabs: snap.tabs.map((t) => (t.id === id ? { id, draft: t.draft, savedId: record.id, title: record.name } : t)) });
+    setRuntime(id, { auth: '', imported: undefined });
+  },
+  /** Saved request `savedId` was renamed or deleted (`record` undefined). */
+  savedChanged(savedId: string, record?: SavedRequest) {
+    set({
+      tabs: snap.tabs.map((t) => {
+        if (t.savedId !== savedId) return t;
+        if (record) return { ...t, title: record.name };
+        const { savedId: _, title: __, ...rest } = t;
+        return rest;
+      }),
+    });
+  },
+  setRuntime,
+  /** Sends tab `id` with REST environment `environment` (id); `extraHeaders` (e.g. a typed Authorization value) go after the draft's headers. */
+  async send(id: string, extraHeaders?: Array<[string, string]>, environment?: string) {
+    const tab = snap.tabs.find((t) => t.id === id);
+    if (!tab || runtimeOf(id).sending) return;
+    const abort = new AbortController();
+    controllers.set(id, abort);
+    setRuntime(id, { sending: true, error: undefined, savedPath: undefined });
+    try {
+      const spec = draftToSpec(tab.draft);
+      if (extraHeaders) spec.headers.push(...extraHeaders);
+      const response = await api.send(spec, tab.savedId, abort.signal, { environment: environment || undefined, draft: tab.draft });
+      if (!abort.signal.aborted) setRuntime(id, { response });
+    } catch (err) {
+      if (!abort.signal.aborted) setRuntime(id, { response: undefined, error: errorOf(err) });
+    } finally {
+      if (controllers.get(id) === abort) {
+        controllers.delete(id);
+        if (snap.tabs.some((t) => t.id === id)) setRuntime(id, { sending: false });
+      }
+    }
+  },
+  cancel(id: string) {
+    controllers.get(id)?.abort();
+    controllers.delete(id);
+    setRuntime(id, { sending: false });
+  },
+};
+
+const subscribe = (l: () => void) => {
+  listeners.add(l);
+  return () => listeners.delete(l);
+};
+const getSnapshot = () => snap;
+
+/** The open tabs, the active id and per-tab runtime state; loads the stored tabs on first use. */
+export function useRestTabs(): Snapshot {
+  useEffect(() => void ensureLoaded(), []);
+  return useSyncExternalStore(subscribe, getSnapshot);
+}

package/src/rest.css

@@ -0,0 +1,36 @@
+/* REST screen: fixed-width list of saved requests, then the editor and response split. */
+.rest-body { display: flex; flex: 1; min-height: 0; }
+.modal:has(.rest-env) { width: min(820px, 100%); }
+.rest-env { display: flex; gap: var(--space-12); min-height: 260px; }
+.rest-env-list { width: 180px; flex-shrink: 0; display: flex; flex-direction: column; gap: var(--space-4); padding-right: var(--space-8); border-right: 1px solid var(--border-soft); overflow-y: auto; }
+.rest-env-vars { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: var(--space-8); }
+.rest-env-table { width: 100%; border-collapse: collapse; }
+.rest-env-table th { text-align: left; font-weight: 500; font-size: var(--fs-xs-plus); color: var(--text-2); padding: var(--space-2) var(--space-4); }
+.rest-env-table td { padding: var(--space-2) var(--space-4); vertical-align: middle; }
+.rest-env-table td input:not([type='checkbox']) { width: 100%; }
+.rest-history { width: 300px; flex-shrink: 0; display: flex; flex-direction: column; gap: var(--space-6); padding: var(--space-8); overflow: hidden; border-left: 1px solid var(--border-soft); }
+.rest-history-head { display: flex; align-items: center; gap: var(--space-6); }
+.rest-history-head .spacer { flex: 1; }
+.rest-history-search { width: 100%; }
+.rest-history-list { flex: 1; min-height: 0; overflow-y: auto; display: flex; flex-direction: column; gap: var(--space-2); }
+.rest-history-item { display: grid; grid-template-columns: 44px 1fr auto; gap: var(--space-2) var(--space-6); padding: 5px var(--space-6); border: 0; border-radius: var(--radius-md); background: transparent; color: var(--text); text-align: left; cursor: pointer; }
+.rest-history-item:hover { background: var(--hover); }
+.rest-history-url { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-family: var(--font-mono); font-size: var(--fs-xs-plus); }
+.rest-history-status { font-family: var(--font-mono); font-size: var(--fs-xs); }
+.rest-history-status.err { color: var(--err); }
+.rest-history-meta { grid-column: 2 / 4; font-size: var(--fs-xs); color: var(--text-3); }
+.rest-list { width: 220px; flex-shrink: 0; display: flex; flex-direction: column; gap: var(--space-4); padding: var(--space-8); overflow-y: auto; border-right: 1px solid var(--border-soft); }
+.rest-list-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: var(--space-4); }
+.rest-item { position: relative; display: flex; align-items: center; border-radius: var(--radius-md); }
+.rest-item:hover, .rest-item.active { background: var(--hover); }
+.rest-item.drop-target { box-shadow: inset 0 2px 0 var(--accent); }
+.rest-item-actions { position: absolute; right: 0; top: 0; bottom: 0; display: none; align-items: center; padding-left: var(--space-12); border-radius: 0 var(--radius-md) var(--radius-md) 0; background: linear-gradient(to right, transparent, var(--hover) 12px); }
+.rest-item:hover .rest-item-actions, .rest-item:focus-within .rest-item-actions { display: flex; }
+.rest-item-main { flex: 1; min-width: 0; display: flex; align-items: center; gap: var(--space-8); padding: var(--space-6); border: 0; background: transparent; color: var(--text); text-align: left; cursor: pointer; }
+.rest-item-name { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.rest-method { flex-shrink: 0; width: 44px; font-family: var(--font-mono); font-size: var(--fs-xs); font-weight: 600; color: var(--text-3); }
+.rest-pane { display: flex; flex-direction: column; gap: var(--space-10); min-width: 0; min-height: 0; height: 100%; padding: var(--space-10) 14px; overflow: auto; }
+.rest-auth { max-width: 420px; }
+.rest-body > :last-child { flex: 1; min-width: 0; }
+.rest-main { display: flex; flex-direction: column; min-height: 0; }
+.rest-main > :last-child { flex: 1; min-height: 0; }

package/src/server.ts

@@ -0,0 +1,111 @@
+import { basename } from 'node:path';
+import { pickFile, saveFileAs, writeFileAtomic } from '@deckbuilderkit/platform';
+import { defineServerView, invalid, isRecord, type Routes } from '@deckbuilderkit/server-core';
+import { fromPlatform, recordRoutes, type RecordStore, type RestHistory, restTabsRoutes } from '@deckbuilderkit/server-mods';
+
+/** The part of the server settings the REST view owns; the app's `Settings` extends it. */
+export interface RestServerSettings {
+  /** REST screen: split fractions of the editor and the response, active environment, history size. */
+  rest?: RestState;
+}
+
+export interface RestState {
+  sizes?: { main: [number, number] };
+  /** Id of the active REST environment; '' or absent = none. */
+  environment?: string;
+  /** Entries kept in the REST request history; 0 turns history off. */
+  historySize?: number;
+}
+
+const validPair = (v: unknown): [number, number] | null =>
+  Array.isArray(v) && v.length === 2 && v.every((n) => typeof n === 'number' && n >= 0 && n <= 1) && Math.abs(v[0] + v[1] - 1) <= 0.01
+    ? [v[0], v[1]]
+    : null;
+
+/** A copy of `raw` when it is a well-formed REST screen state, else null. */
+export function validRest(raw: unknown): RestState | null {
+  if (!isRecord(raw)) return null;
+  const out: RestState = {};
+  if (raw.sizes !== undefined) {
+    if (!isRecord(raw.sizes)) return null;
+    const main = validPair(raw.sizes.main);
+    if (!main) return null;
+    out.sizes = { main };
+  }
+  if (raw.environment !== undefined) {
+    if (typeof raw.environment !== 'string' || (raw.environment !== '' && !/^[\w-]{1,64}$/.test(raw.environment))) return null;
+    out.environment = raw.environment;
+  }
+  if (raw.historySize !== undefined) {
+    if (!Number.isInteger(raw.historySize) || (raw.historySize as number) < 0 || (raw.historySize as number) > 5000) return null;
+    out.historySize = raw.historySize as number;
+  }
+  return out;
+}
+
+/** `rest.historySize` (default 100; 0 = no REST history). */
+export const restHistorySizeOf = (s: RestServerSettings) => {
+  const n = s.rest?.historySize;
+  return typeof n === 'number' && Number.isInteger(n) && n >= 0 ? n : 100;
+};
+
+const MAX_IMPORT_BYTES = 1_000_000;
+const HTTP_FILE_FILTERS = [
+  { name: 'HTTP', patterns: ['*.http', '*.rest'] },
+  { name: 'All files', patterns: ['*.*'] },
+];
+
+/** A saved request record; the store itself belongs to the app (its `/api/http/send` reads the saved Authorization value). */
+interface SavedRequestRecord {
+  name: string;
+  request: unknown;
+  auth?: unknown;
+}
+
+/**
+ * Server half of the REST view: saved requests, open tabs, request history and the `rest` settings group.
+ * Stores come from the app (`ctx.stores`): `requests` (a `RecordStore`) and `restHistory` (a `RestHistory`, whose `append` the app's
+ * `httpRoutes` `onSend` calls). `/api/http/*` and the environments stay app-mounted (the Explorer's curl panel uses them too).
+ */
+export const restServerView = () =>
+  defineServerView<RestServerSettings>({
+    id: 'rest',
+    routes: (ctx): Routes => {
+      const requests = ctx.stores.requests as RecordStore<SavedRequestRecord>;
+      const history = ctx.stores.restHistory as RestHistory;
+      return {
+        ...recordRoutes(requests, '/api/requests'),
+        // The saved Authorization value, only for Copy as curl.
+        'GET /api/requests/auth': async ({ query }) => {
+          const id = query.get('id');
+          if (!id) throw invalid('badRequest', 'Invalid request.');
+          await requests.get(id);
+          return { value: ((await requests.secret(id, 'auth')) as string | undefined) ?? null };
+        },
+        ...restTabsRoutes({ dir: ctx.dataDir }),
+        // The target comes from the save dialog on this side; the client never names a path.
+        'POST /api/requests/save-curl': async ({ json }) => {
+          const { text } = await json<{ text?: unknown }>();
+          if (typeof text !== 'string' || text.length > MAX_IMPORT_BYTES) throw invalid('badRequest', 'Invalid request.');
+          const path = await saveFileAs({ suggestedName: 'request.curl', filters: [{ name: 'cURL', patterns: ['*.curl', '*.sh'] }, { name: 'All files', patterns: ['*.*'] }] }).catch(fromPlatform);
+          if (!path) return { path: null };
+          await writeFileAtomic(path, `${text}\n`).catch(fromPlatform);
+          return { path };
+        },
+        // The file's text goes to the client for parsing; its path never does.
+        'POST /api/requests/import-file': async () => {
+          const path = await pickFile({ filters: HTTP_FILE_FILTERS }).catch(fromPlatform);
+          if (!path) return { text: null };
+          const file = Bun.file(path);
+          if (file.size > MAX_IMPORT_BYTES) throw invalid('importTooLarge', 'The file is too large to import.');
+          return { name: basename(path), text: await file.text() };
+        },
+        'GET /api/rest/history': async ({ query }) => history.list({ q: query.get('q') ?? undefined }),
+        'DELETE /api/rest/history': async () => {
+          await history.clear();
+          return {};
+        },
+      };
+    },
+    settings: { validate: { rest: validRest } },
+  });

package/src/settings.ts

@@ -0,0 +1,48 @@
+import type { HttpRequestDraft } from '@deckbuilderkit/editor';
+import type { SectionPath, SettingDef } from '@deckbuilderkit/ui';
+
+/** The stored REST screen state. */
+export interface RestSettings {
+  sizes?: { main: [number, number] };
+  /** Id of the active REST environment; '' or absent = none. */
+  environment?: string;
+  /** Entries kept in the REST request history; 0 turns history off. */
+  historySize?: number;
+}
+
+/** The part of the app settings the REST view reads and writes; the app's `Settings` extends it. */
+export interface RestViewSettings {
+  /** State of the REST screen; the server validates it. */
+  rest?: RestSettings;
+}
+
+export interface SavedRequest {
+  id: string;
+  name: string;
+  request: HttpRequestDraft;
+  auth?: { hasSecret: true };
+}
+
+export interface RestTabsFile {
+  version: 1;
+  tabs: Array<{ id: string; draft: HttpRequestDraft; savedId?: string; title?: string }>;
+  active?: string;
+}
+
+const rest: SectionPath = ['rest'];
+
+export const restSettingDefs: SettingDef<RestViewSettings>[] = [
+  {
+    id: 'rest.historySize',
+    kind: 'number',
+    section: rest,
+    order: 10,
+    label: 'settings.rest.historySize',
+    description: 'settings.rest.historySize.hint',
+    default: 100,
+    min: 0,
+    max: 5000,
+    get: (s) => s.rest?.historySize ?? 100,
+    set: (s, historySize) => ({ rest: { ...s.rest, historySize } }),
+  },
+];

package/src/view.tsx

@@ -0,0 +1,28 @@
+import { lazy } from 'react';
+import { defineView } from '@deckbuilderkit/ui';
+import { bindRestClient, type RestClient } from './client';
+import { restCommands } from './commands';
+import { en, ptBR } from './i18n';
+import { restSettingDefs, type RestViewSettings } from './settings';
+
+const RestScreen = lazy(() => import('./RestScreen').then((m) => ({ default: m.RestScreen })));
+
+export interface RestViewOptions {
+  /** i18n key of the nav section title. */
+  group: string;
+  order: number;
+  /** The server calls the screen makes. */
+  client: RestClient;
+}
+
+export function restView({ group, order, client }: RestViewOptions) {
+  bindRestClient(client);
+  return defineView<'rest', RestViewSettings, 'nav.rest'>({
+    id: 'rest',
+    nav: { group, icon: 'send', label: 'nav.rest', order },
+    render: ({ settings, onSave }) => <RestScreen settings={settings} onSave={onSave} />,
+    commands: restCommands,
+    settings: { defs: restSettingDefs },
+    messages: { en, 'pt-BR': ptBR },
+  });
+}

package/src/web.ts

@@ -0,0 +1,4 @@
+export { type RestClient } from './client';
+export { type RestMessageKey } from './i18n';
+export { type RestSettings, type RestTabsFile, type RestViewSettings, type SavedRequest } from './settings';
+export { restView, type RestViewOptions } from './view';