@qoretechnologies/reqraft 0.10.54 → 0.10.55-pr.115.g37abdfc

package/src/hooks/useTemplates.ts

@@ -13,6 +13,39 @@ export interface IUseTemplates {
 
 export const TemplatesCache = new Map<string, IReqoreFormTemplates>();
 
+/**
+ * Hand this hook a `getContextData` payload the host has already fetched.
+ *
+ * The host and this library keep SEPARATE caches over one API, so a page that
+ * has already paid for the context data pays again here — and, worse, waits for
+ * it: `FormEngine` will not render a field before its templates exist, because
+ * an any-typed field with no templates falls back to the type picker and asks
+ * the author to choose `string`/`int`/`hash` for a value they already captured.
+ *
+ * Measured on the live alert rule: three form sections were placeholders from
+ * 1459ms to 2039ms and, when they cleared, 193 elements that had been on screen
+ * for ~590ms dropped 67px, because the placeholder is not the height of the
+ * form it stands in for. Seeded, the form has its templates on its FIRST render
+ * and there is no placeholder to swap out at all.
+ *
+ * Same shape as `seedQueryCache` for the type catalogue, and deliberately
+ * first-write-wins: a real fetch that has already answered is not overwritten.
+ */
+export const seedTemplatesCache = (
+  interfaceContext: string,
+  payload: ITemplatesPayload
+): void => {
+  if (!interfaceContext || TemplatesCache.has(interfaceContext)) {
+    return;
+  }
+
+  const templates = buildTemplates(payload);
+
+  if (templates) {
+    TemplatesCache.set(interfaceContext, templates);
+  }
+};
+
 /**
  * Templates for form fields. Ported from qorus-ide `useTemplates` with one
  * deliberate difference: fetching `system/getContextData` is **opt-in** via
@@ -29,6 +62,14 @@ export const useTemplates = (
 
   const globalTemplates = useAsyncRetry(async () => {
     if (shouldFetch) {
+      /* Already answered — by a previous mount or by the host seeding it. The
+         cache was consulted for `loading` and for the value but not here, so a
+         seeded page still issued the request it had been handed the answer to. */
+      const cached = TemplatesCache.get(interfaceContext!);
+      if (cached) {
+        return cached;
+      }
+
       const serverTemplates = await query<ITemplatesPayload>({
         url: `system/getContextData?interface_context=${interfaceContext}`,
         method: 'PUT',

package/src/hooks/useWebSocket/useWebsocket.stories.tsx

@@ -6,6 +6,7 @@ import { Server } from 'mock-socket';
 import { useEffect, useState } from 'react';
 import { useMount } from 'react-use';
 import { sleep, testsClickButton, testsWaitForText } from '../../../__tests__/utils';
+import { storySocketUrl } from '../../stories/storyNetwork';
 import { StoryMeta } from '../../types';
 import { ReqraftWebSocketsManager } from '../../utils/websocket';
 import { IUseReqraftWebSocketOptions, useReqraftWebSocket } from './useWebSocket';
@@ -40,7 +41,7 @@ const CompWithHook = (args: IUseReqraftWebSocketOptions) => {
 const meta = {
   title: 'Hooks/useWebSocket',
   async beforeEach({ parameters }: { parameters: Record<string, any> }) {
-    const url = `wss://hq.qoretechnologies.com:8092/log-test?token=${process.env.REACT_APP_QORUS_TOKEN}`;
+    const url = storySocketUrl('log-test');
     let server = new Server(url);
     let killTimeout: NodeJS.Timeout;
     /** Set while the server is dead: every connection that lands is closed. */

package/src/index.tsx

@@ -36,7 +36,20 @@ export type {
   ICurrentUser,
   ICurrentUserStore,
 } from './stores/currentUser/currentUser';
-export { fetchConfig, query } from './utils/fetch';
+export {
+  fetchConfig,
+  query,
+  queryRaw,
+  reqraftApiPath,
+  reqraftCacheKey,
+  setupFetch,
+} from './utils/fetch';
+export type {
+  IReqraftFetchConfig,
+  IReqraftFetchResponse,
+  IReqraftQueryConfig,
+  IReqraftRawResponse,
+} from './utils/fetch';
 export * from './utils/websocket';
 export { ReqraftLspClient } from './utils/lspClient';
 export type { IReqraftLspClientOptions } from './utils/lspClient';

package/src/stores/currentUser/currentUser.stories.tsx

@@ -1,6 +1,7 @@
 import { ReqoreP, ReqoreSpinner, ReqoreTree } from '@qoretechnologies/reqore';
 import { StoryObj } from '@storybook/react-vite';
 import { testsWaitForText } from '../../../__tests__/utils';
+import { storyApiUrl } from '../../stories/storyNetwork';
 import { StoryMeta } from '../../types';
 import { currentUserStore } from './currentUser';
 
@@ -9,7 +10,7 @@ const meta = {
   parameters: {
     mockData: [
       {
-        url: 'https://hq.qoretechnologies.com:8092/api/latest/users?action=current',
+        url: storyApiUrl('users?action=current'),
         method: 'GET',
         status: 200,
         response: {

package/src/stories/storyNetwork.ts

@@ -0,0 +1,92 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+// Where a story's network goes: the instance its Reqraft points at, the URLs
+// its mocks must intercept, and the requests every story is mocked for.
+//
+// `query()` and `ReqraftWebSocket` build absolute URLs from the configured
+// instance, and both mock layers match on the host as well as the path —
+// storybook-addon-mock keys on `host + pathname`, mock-socket on the URL minus
+// its query. A mock written against a hard-coded host stops matching the moment
+// the instance is overridden, and the request goes out to the real network
+// instead, silently. Build mock URLs with the helpers below.
+import { defaultQorusTypes } from '../hooks/useQorusTypes';
+import { buildReqraftApiUrl } from '../utils/fetch';
+import { buildReqraftSocketUrl } from '../utils/websocket';
+
+/**
+ * What storybook-addon-mock accepts as a response. Anything else — a bare
+ * number or string — fails the addon's validation and the entry is kept but
+ * never matched, so the request goes out to the network with no warning.
+ */
+export type TStoryMockResponse = object | ((request: unknown) => unknown);
+
+export interface IStoryMockRequest {
+  url: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  status: number;
+  response: TStoryMockResponse;
+}
+
+/**
+ * The instance every story's Reqraft is initialized with. Override it with
+ * `REACT_APP_QORUS_INSTANCE` (or `QORUS_INSTANCE`) to run live stories against
+ * your own Qorus; mocks built from it follow the override.
+ */
+export const STORY_QORUS_INSTANCE =
+  process.env.REACT_APP_QORUS_INSTANCE || 'https://hq.qoretechnologies.com:8092/';
+
+/** The URL `query()` requests for `path`. */
+export const storyApiUrl = (path: string): string =>
+  buildReqraftApiUrl(STORY_QORUS_INSTANCE, path);
+
+/**
+ * The URL `ReqraftWebSocket` dials for `path`, token omitted — mock-socket
+ * matches servers without the query string.
+ */
+export const storySocketUrl = (path: string): string =>
+  buildReqraftSocketUrl(STORY_QORUS_INSTANCE, path);
+
+/** A GET of `path` answered with `response`. */
+const mockGet = (path: string, response: TStoryMockResponse): IStoryMockRequest[] => [
+  { url: storyApiUrl(path), method: 'GET', status: 200, response },
+];
+
+/**
+ * The type catalogue, pinned to the built-in list. `useQorusTypes` uses a
+ * reachable server's list *instead of* the built-in one, so an unmocked story
+ * renders whichever labels that server happens to have — and every FormEngine
+ * shows its loading skeleton until the request settles, which against an
+ * unreachable instance is never.
+ */
+const QORUS_TYPE_INFO_MOCK_DATA = mockGet('system/qorus-type-info', defaultQorusTypes);
+
+/**
+ * The system expression catalogue, empty. `useExpressions` fetches it whenever
+ * functions are allowed — even when the story passes its own list, which is
+ * merged in as extras — and TemplateField shows a skeleton in place of "Use
+ * Expression" until it arrives. Stories that need functions provide them
+ * (`expressions`, or their own `mockData` for this URL).
+ */
+const EXPRESSIONS_CATALOGUE_MOCK_DATA = mockGet('system?action=expressions&context=ui', []);
+
+/**
+ * `ReqraftWebSocket`'s server probe, which every reconnect attempt awaits
+ * before it dials. Unanswered, no attempt is ever made — a mock socket server
+ * that comes back is never reconnected to, and one that stays down is never
+ * given up on. The probe only needs an answer; its body is not read.
+ */
+const SERVER_STATUS_MOCK_DATA = mockGet('system/pid', {});
+
+/**
+ * Requests components make on their own, whatever the story is about —
+ * mounting a FormEngine fetches the type catalogue; allowing functions fetches
+ * the expression catalogue; a reconnecting socket probes the server.
+ * Registered for every story as storybook-addon-mock's `globalMockData`
+ * (`.storybook/preview.tsx`, and mirrored for the Vitest run in
+ * `.storybook/vitest.setup.ts`); a story's own `mockData` entry for the same
+ * URL takes precedence.
+ */
+export const GLOBAL_STORY_MOCK_DATA: IStoryMockRequest[] = [
+  ...QORUS_TYPE_INFO_MOCK_DATA,
+  ...EXPRESSIONS_CATALOGUE_MOCK_DATA,
+  ...SERVER_STATUS_MOCK_DATA,
+];

package/src/utils/fetch.ts

@@ -13,6 +13,21 @@ export interface IReqraftFetchResponse<T> {
   ok: boolean;
   code?: number;
   error?: any;
+  /**
+   * The parsed error body on a non-ok response, when the server sent JSON.
+   *
+   * Qorus errors carry `{ err, desc }`; `error` above is only the HTTP reason
+   * phrase, which is why a caller that wanted the sentence had to reach into
+   * `data`. Consumers that need the code (`err`) or the message (`desc`) should
+   * read this rather than re-parsing.
+   */
+  errorBody?: Record<string, any>;
+  /**
+   * The response text when the body was NOT valid JSON. A non-JSON error would
+   * otherwise arrive as `{}` with only a reason phrase, discarding whatever the
+   * server actually said.
+   */
+  rawText?: string;
   response: Response;
 }
 
@@ -39,26 +54,104 @@ export const setupFetch = ({
   }
 };
 
+/**
+ * The API path a caller asked for, without the leading slash the prefix already
+ * carries.
+ *
+ * `doFetchData` builds `${instance}api/latest/${url}`, and that prefix ENDS in a
+ * slash — so a caller writing `/dataprovider/arg_schemas/x` produced
+ * `api/latest//dataprovider/arg_schemas/x`. Qorus serves it, which is how both
+ * spellings survived side by side (`useArgSchema` writes one, `CompactRow` and
+ * `AutoFormField` the other), but it is not harmless: the query cache is keyed
+ * on the url, so `/x` and `x` were two cache entries and two requests for one
+ * resource.
+ *
+ * Normalised here, once, rather than at each call site — the convention is
+ * invisible from a caller's point of view and the next one would get it wrong
+ * again. Only applied when the prefix is added: a caller that opts out of the
+ * prefix owns its whole path, leading slash included.
+ */
+export const reqraftApiPath = (url: string, noApiPrefix: boolean = false): string =>
+  noApiPrefix ? url : url.replace(/^\/+/, '');
+
+/**
+ * A cheap, stable, non-reversible marker for a bearer token.
+ *
+ * Two callers holding DIFFERENT tokens are two identities and must not share a
+ * cached response, so the token has to take part in the cache key — but a raw
+ * token in a key is a credential sitting in devtools' query inspector. djb2 is
+ * enough to tell two tokens apart, which is all the key needs.
+ */
+const tokenMarker = (token?: string): string => {
+  if (!token) {
+    return '';
+  }
+  let hash = 5381;
+  for (let index = 0; index < token.length; index++) {
+    hash = ((hash << 5) + hash + token.charCodeAt(index)) | 0;
+  }
+  return `:t${(hash >>> 0).toString(36)}`;
+};
+
+/**
+ * The one cache key for a request, used by every caller in every downstream
+ * project so that one resource is one entry and one in-flight request.
+ *
+ * `instance` and the token take part because both change WHICH server and WHOSE
+ * data answers: a call that overrides the instance, or that carries an explicit
+ * token, is a different resource that happens to share a path.
+ */
+export const reqraftCacheKey = ({
+  url,
+  method = 'GET',
+  body,
+  noApiPrefix,
+  instance,
+  token,
+}: Pick<IReqraftQueryConfig, 'url' | 'method' | 'body' | 'noApiPrefix' | 'instance' | 'token'>) =>
+  `${reqraftApiPath(url, noApiPrefix)}:${method}:${JSON.stringify(body || {})}${
+    instance && instance !== fetchConfig.instance ? `:@${instance}` : ''
+  }${tokenMarker(token)}`;
+
+/**
+ * The URL `query()` requests for `url` on `instance` — the single definition.
+ * Story mocks build their URLs with it too, so they cannot drift from what the
+ * code actually dials.
+ *
+ * `noApiPrefix` means the caller owns the WHOLE url — an absolute address for
+ * another service, which is the only thing reqraft itself uses it for
+ * (`useExpressions` sets it exactly when `expressionsUrl` is `http(s)://…`).
+ * Prepending the instance there built `https://instance:8011/https://other/…`.
+ */
+export const buildReqraftApiUrl = (instance: string, url: string, noApiPrefix = false): string =>
+  noApiPrefix ? url : `${instance}api/latest/${reqraftApiPath(url)}`;
+
 async function doFetchData(
   url: string,
   method = 'GET',
   body?: { [key: string]: any },
   noApiPrefix = false,
-  instance = fetchConfig.instance
+  instance = fetchConfig.instance,
+  headers?: Record<string, string>,
+  token?: string
 ): Promise<Response> {
   // We do not check for token because Qorus now handles auth automatically via cookies
   // token is only supplied in a dev environment
-  const headers = {
+  const finalHeaders: Record<string, string> = {
     'Content-Type': 'application/json',
+    ...(headers ?? {}),
   };
 
-  if (fetchConfig.instanceToken && !fetchConfig.instanceRbacDisabled) {
-    headers['Authorization'] = `Bearer ${fetchConfig.instanceToken}`;
+  const finalToken =
+    token ?? (fetchConfig.instanceRbacDisabled ? undefined : fetchConfig.instanceToken);
+
+  if (finalToken && !finalHeaders['Authorization']) {
+    finalHeaders['Authorization'] = `Bearer ${finalToken}`;
   }
 
-  return fetch(`${instance}${noApiPrefix ? '' : 'api/latest/'}${url}`, {
+  return fetch(buildReqraftApiUrl(instance, url, noApiPrefix), {
     method,
-    headers,
+    headers: finalHeaders,
     body: JSON.stringify(body),
     credentials: 'include',
   }).catch((error) => {
@@ -75,11 +168,123 @@ export interface IReqraftQueryConfig {
   body?: Record<string | number, any>;
   cache?: boolean;
   queryClient?: QueryClient;
+  /**
+   * The `url` is a complete address and is used verbatim — neither the instance
+   * nor `api/latest/` is prepended, and its leading slash is left alone. For
+   * reaching a service that is not this Qorus instance.
+   */
   noApiPrefix?: boolean;
   /** Override the global instance URL for this single call (e.g. to target a different port). */
   instance?: string;
+  /** Extra request headers, merged over the default `Content-Type`. */
+  headers?: Record<string, string>;
+  /**
+   * A bearer token for THIS call, instead of the configured instance token —
+   * for a route that is authenticated as somebody other than the current app
+   * session. Takes part in the cache key.
+   */
+  token?: string;
+  /**
+   * An explicit cache key, for a caller that must group or separate requests
+   * differently from the default `path:method:body` identity.
+   */
+  cacheKey?: string;
+  /**
+   * How long a cached response counts as fresh, in ms. Defaults to 5 minutes
+   * when `cache` is on. `Infinity` keeps it for the life of the page — what a
+   * caller wants for a catalogue that cannot change without a server restart.
+   */
+  staleTime?: number;
+  /**
+   * Whether a 401 on this request should send the page to
+   * `fetchConfig.unauthorizedRedirect`. Defaults to `true`.
+   *
+   * A 401 only means "this app's session expired" when the request actually
+   * carried this app's credential. A call that targets another service, or that
+   * hands over an explicit token, proves nothing about the session — signing the
+   * user out because an unrelated credential was refused is wrong. Callers that
+   * own their own auth policy (or that must never navigate, such as a test
+   * runner or a Storybook preview) pass `false`.
+   */
+  redirectOnUnauthorized?: boolean;
 }
 
+/**
+ * Reads a response body without consuming it, and says whether it was JSON.
+ *
+ * `data` stays `{}` for a body that is empty or not JSON, which is the contract
+ * reqraft's consumers have always been given. The text is handed back separately
+ * as `rawText` so an error that was not JSON still carries whatever the server
+ * said, instead of being flattened to a bare reason phrase.
+ */
+const readBody = async (response: Response): Promise<{ data: any; rawText?: string }> => {
+  const rawText = await response.clone().text();
+
+  try {
+    return { data: JSON.parse(rawText) };
+  } catch (_error) {
+    return { data: {}, rawText };
+  }
+};
+
+/**
+ * The single request mechanism.
+ *
+ * Every request in reqraft AND in the projects built on it goes through here,
+ * so that one resource has one cache entry and one in-flight request no matter
+ * which library, hook or component asked for it. A downstream project that
+ * keeps its own fetch helper (qorus-ide's `fetchData` is the one this was
+ * written for) should adapt onto this rather than hold a second cache: two
+ * caches over one API cannot see each other's in-flight requests, so any
+ * resource both libraries want is fetched twice by construction.
+ */
+/**
+ * Put a resource the HOST already has into the cache `query` reads.
+ *
+ * The comment on `query` states the problem: two caches over one API cannot see
+ * each other's in-flight requests, so any resource both libraries want is
+ * fetched twice by construction. This is the seam that lets a host settle it
+ * without either side giving up its own loader.
+ *
+ * The case it was written for: the Qorus IDE warm-starts
+ * `/system/qorus-type-info` from `index.html`, before the bundle has even
+ * parsed, because its whole boot gates on it — and then reqraft's own
+ * `useQorusTypes` asked for it again on the first form's mount. Measured on the
+ * live IDE at 419ms and 2777ms, the same URL, the same answer.
+ *
+ * Seeding is enough to stop the second request: `query` goes through
+ * `fetchQuery` with a `staleTime`, and a fresh entry is returned without the
+ * query function ever running. `useFetch` reads the same cache directly, so it
+ * also skips its loading state and renders the answer on its first paint.
+ *
+ * Only for a resource the host has genuinely FETCHED. Seeding a guess would
+ * make every consumer believe a request had succeeded.
+ */
+export const seedQueryCache = <T>({
+  url,
+  method = 'GET',
+  body,
+  noApiPrefix,
+  instance,
+  token,
+  data,
+  queryClient = ReqraftQueryClient,
+}: Pick<
+  IReqraftQueryConfig,
+  'url' | 'method' | 'body' | 'noApiPrefix' | 'instance' | 'token' | 'queryClient'
+> & { data: T }): void => {
+  const key = reqraftCacheKey({ url, method, body, noApiPrefix, instance, token });
+
+  queryClient.setQueryData([key], {
+    data,
+    rawText: undefined,
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+    response: undefined,
+  });
+};
+
 export async function query<T>({
   url,
   method = 'GET',
@@ -88,47 +293,54 @@ export async function query<T>({
   queryClient = ReqraftQueryClient,
   noApiPrefix = false,
   instance,
+  headers,
+  token,
+  cacheKey,
+  staleTime,
+  redirectOnUnauthorized = true,
 }: IReqraftQueryConfig): Promise<IReqraftFetchResponse<T>> {
   const shouldCache = method === 'DELETE' || method === 'POST' ? false : cache;
-  const cacheKey = `${url}:${method}:${JSON.stringify(body || {})}`;
+  const key = cacheKey ?? reqraftCacheKey({ url, method, body, noApiPrefix, instance, token });
 
   const requestData = await queryClient.fetchQuery({
-    queryKey: [cacheKey],
+    queryKey: [key],
     queryFn: async () => {
-      const response = await doFetchData(url, method, body, noApiPrefix, instance);
+      const response = await doFetchData(url, method, body, noApiPrefix, instance, headers, token);
 
-      if (response.status === 401 && fetchConfig.unauthorizedRedirect) {
-        window.location.href = fetchConfig.unauthorizedRedirect(window.location);
+      if (response.status === 401 && redirectOnUnauthorized && fetchConfig.unauthorizedRedirect) {
+        // `replace`, not an assignment: the page being left is dead, and a
+        // history entry for it means Back lands on a view that can only 401
+        // again.
+        window.location.replace(fetchConfig.unauthorizedRedirect(window.location));
       }
 
-      const clone = response.clone();
-      let data: any;
-
-      try {
-        data = await clone.json();
-      } catch (error) {
-        data = {};
-      }
+      const { data, rawText } = await readBody(response);
 
       return {
         data,
+        rawText,
         ok: response.ok,
         status: response.status,
         statusText: response.statusText,
         response,
       };
     },
-    staleTime: shouldCache ? CACHE_EXPIRATION_TIME : 0,
+    staleTime: shouldCache ? (staleTime ?? CACHE_EXPIRATION_TIME) : 0,
   });
 
   if (!requestData.ok) {
-    queryClient.invalidateQueries({ queryKey: [cacheKey] });
+    queryClient.invalidateQueries({ queryKey: [key] });
 
     return {
       data: requestData.data,
       ok: false,
       code: requestData.status,
       error: requestData.statusText,
+      // Only when the body really was JSON: `data` is `{}` for a non-JSON body,
+      // and an empty object masquerading as a parsed error tells a caller
+      // nothing while looking like it did.
+      errorBody: requestData.rawText === undefined ? requestData.data : undefined,
+      rawText: requestData.rawText,
       response: requestData.response,
     };
   }
@@ -137,6 +349,84 @@ export async function query<T>({
     data: requestData.data,
     ok: true,
     code: requestData.status,
+    rawText: requestData.rawText,
     response: requestData.response,
   };
 }
+
+export interface IReqraftRawResponse {
+  ok: boolean;
+  code?: number;
+  error?: string;
+  /** The response bytes. Undefined on a non-ok response. */
+  blob?: Blob;
+  /** The `Content-Type` the bytes were served with, without parameters. */
+  mime?: string;
+}
+
+/**
+ * Fetch a resource whose body is NOT JSON — a file, an export, a log.
+ *
+ * Shares `doFetchData` with `query`, which owns the API prefix, the bearer token
+ * and `credentials: 'include'`. The point is that raw responses do not become a
+ * second, drifting copy of that auth handling.
+ *
+ * Nothing is cached: these payloads are large and read once.
+ *
+ * @param accept the `Accept` header. Endpoints that negotiate on the file's own
+ *   MIME type answer **406** unless the caller accepts that type, and the caller
+ *   usually cannot know it ahead of time, so this accepts anything by default.
+ */
+export async function queryRaw({
+  url,
+  method = 'GET',
+  body,
+  noApiPrefix = false,
+  instance,
+  headers,
+  token,
+  accept = '*/*',
+  redirectOnUnauthorized = true,
+}: Omit<IReqraftQueryConfig, 'cache' | 'queryClient' | 'cacheKey' | 'staleTime'> & {
+  accept?: string;
+}): Promise<IReqraftRawResponse> {
+  try {
+    const response = await doFetchData(
+      url,
+      method,
+      body,
+      noApiPrefix,
+      instance,
+      {
+        Accept: accept,
+        ...(headers ?? {}),
+      },
+      token
+    );
+
+    if (response.status === 401 && redirectOnUnauthorized && fetchConfig.unauthorizedRedirect) {
+      window.location.replace(fetchConfig.unauthorizedRedirect(window.location));
+    }
+
+    if (!response.ok) {
+      let error: string;
+      try {
+        // an error body is still JSON even when the success body is not
+        error = (await response.json()).desc ?? response.statusText;
+      } catch (_error) {
+        error = response.statusText;
+      }
+
+      return { ok: false, code: response.status, error };
+    }
+
+    return {
+      ok: true,
+      code: response.status,
+      blob: await response.blob(),
+      mime: (response.headers.get('content-type') ?? '').split(';')[0].trim() || undefined,
+    };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}