@k2b/cloud 0.6.0 → 0.8.0

package/src/api/search/schemas.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { CloudResourceRefSchema } from "../../contracts";
+import { CapabilitySearchTagManifestSchema } from "../../contracts/capabilities";
 
 const TAG_PATTERN = /^[^\s#]+$/;
 const SEARCH_BASE_URL = "https://cloud.invalid";
@@ -29,26 +30,35 @@ const TagArraySchema = z.preprocess(
     .transform((tags) => [...new Set(tags.map((tag) => tag.toLowerCase()))]),
 );
 
-export const SearchQuerySchema = z.object({
-  q: z
-    .string()
-    .max(500)
-    .optional()
-    .default("")
-    .transform((query) => query.trim()),
-  tag: TagArraySchema.optional().default([]),
-  app: z.string().trim().min(1).max(120).optional(),
-  require_reader: z
-    .enum(["true"])
-    .optional()
-    .transform((value) => value === "true"),
-  provider_limit: z.coerce.number().int().min(1).max(30).optional().default(10),
-});
+export const SearchQuerySchema = z
+  .object({
+    q: z
+      .string()
+      .max(500)
+      .optional()
+      .default("")
+      .transform((query) => query.trim()),
+    tag: TagArraySchema.optional().default([]),
+    app: z.string().trim().min(1).max(120).optional(),
+    scope_tag: z.string().trim().min(1).max(64).regex(TAG_PATTERN).toLowerCase().optional(),
+    scope_type: CloudResourceRefSchema.shape.type.optional(),
+    scope_id: CloudResourceRefSchema.shape.id.optional(),
+    require_reader: z
+      .enum(["true"])
+      .optional()
+      .transform((value) => value === "true"),
+    provider_limit: z.coerce.number().int().min(1).max(30).optional().default(10),
+  })
+  .refine((value) => Boolean(value.scope_type) === Boolean(value.scope_id), { message: "Both scope_type and scope_id are required" })
+  .refine((value) => !value.scope_tag || (Boolean(value.app) && !value.scope_type), {
+    message: "A tag context requires an app and cannot include a resource scope",
+  });
 
 export const SearchAppSchema = z.object({
   id: z.string(),
   name: z.string(),
   icon: z.string(),
+  tags: z.array(CapabilitySearchTagManifestSchema).optional(),
 });
 
 export const SearchItemSchema = z.object({
@@ -72,6 +82,7 @@ export const SearchResponseSchema = z.object({
   items: z.array(SearchItemSchema),
   apps: z.array(SearchAppSchema),
   unsupportedTags: z.array(z.string()).optional(),
+  failedApps: z.array(z.string()).optional(),
 });
 
 export type SearchApp = z.infer<typeof SearchAppSchema>;

package/src/api/search.bench.ts

@@ -16,7 +16,7 @@ const PROVIDER_LATENCY_MS = 5;
 const ISSUER = "https://cloud.test";
 
 const capabilities = defineCapabilities({
-  protocolVersion: 1,
+  protocolVersion: 2,
   types: { item: { title: "Item", description: "A benchmark item." } },
   queries: {
     search: {

package/src/api/search.ts

@@ -1,6 +1,7 @@
 import { Hono, type MiddlewareHandler } from "hono";
 import { describeRoute } from "hono-openapi";
 import { readBoundedJson } from "../_internal/bounded-json";
+import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import { listCapabilities } from "../_internal/registry";
 import type { CapabilityRegistryEntry } from "../contracts";
 import {
@@ -20,6 +21,7 @@ import { LOCALE_HEADER } from "../shared/locale";
 import { type SearchItem, SearchItemSchema, SearchQuerySchema, SearchResponseSchema } from "./search/schemas";
 
 const log = logger("search");
+const SearchProviderResultSchema = capabilityResultSchema(UniversalSearchDataSchema);
 
 /**
  * Maximum items returned to the client after merging across providers.
@@ -28,7 +30,6 @@ const log = logger("search");
 const GLOBAL_RESULT_LIMIT = 30;
 const PROVIDER_CONCURRENCY = 8;
 const PROVIDER_TIMEOUT_MS = 8_000;
-const SIGNING_TIMEOUT_MS = 500;
 
 type HttpSearchProvider = {
   appId: string;
@@ -36,6 +37,7 @@ type HttpSearchProvider = {
   appIcon: string;
   endpoint: string;
   tags: string[];
+  scopeTypes: string[];
   typeIds: Set<string>;
   schemaHash: string;
 };
@@ -55,6 +57,7 @@ const getSearchProviders = (entries: CapabilityRegistryEntry[]): HttpSearchProvi
               appIcon: entry.appIcon,
               endpoint: `${entry.endpoint}/queries/${encodeURIComponent(query.localId)}`,
               tags: query.universalSearch.tags.flatMap((tag) => [tag.tag, ...(tag.aliases ?? [])]),
+              scopeTypes: (query.universalSearch.scopeTypes ?? []).map((type) => `${entry.appId}.${type}`),
               typeIds: new Set(entry.manifest.types.map((type) => `${entry.appId}.${type.localId}`)),
               schemaHash: query.schemaHash,
             },
@@ -125,8 +128,8 @@ const settleBounded = async <T, R>(items: readonly T[], concurrency: number, run
 const waitWithin = <T>(value: Promise<T>, signal: AbortSignal): Promise<T> =>
   new Promise<T>((resolve, reject) => {
     const aborted = () => reject(signal.reason);
-    if (signal.aborted) return aborted();
-    signal.addEventListener("abort", aborted, { once: true });
+    // The work has already started; observe its rejection even if the client
+    // disconnected before we began waiting.
     value.then(
       (result) => {
         signal.removeEventListener("abort", aborted);
@@ -137,6 +140,8 @@ const waitWithin = <T>(value: Promise<T>, signal: AbortSignal): Promise<T> =>
         reject(error);
       },
     );
+    if (signal.aborted) return aborted();
+    signal.addEventListener("abort", aborted, { once: true });
   });
 
 /**
@@ -183,11 +188,26 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
         );
       }
       const providers = getSearchProviders(entries);
-      const apps = [
-        ...new Map(
-          providers.map((provider) => [provider.appId, { id: provider.appId, name: provider.appName, icon: provider.appIcon }]),
-        ).values(),
-      ].sort((a, b) => a.name.localeCompare(b.name));
+      const requestLocale = preferredLocale(c.req.raw.headers) ?? "en";
+      const apps = entries
+        .flatMap((entry) => {
+          const manifest = resolveCapabilityManifestPresentation(entry.manifest, entry.presentation, requestLocale);
+          const queries = manifest.queries.filter((operation) => operation.universalSearch);
+          if (!queries.length) return [];
+          return [
+            {
+              id: entry.appId,
+              name: entry.appName,
+              icon: entry.appIcon,
+              tags: [
+                ...new Map(
+                  queries.flatMap((operation) => (operation.universalSearch?.tags ?? []).map((tag) => [tag.tag, tag] as const)),
+                ).values(),
+              ],
+            },
+          ];
+        })
+        .sort((a, b) => a.name.localeCompare(b.name));
       const readableTypes = new Set(
         entries.flatMap((entry) => entry.manifest.types.filter((type) => type.reader).map((type) => `${entry.appId}.${type.localId}`)),
       );
@@ -199,11 +219,19 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
       // returned to the client so it can render a helpful empty state.
       const knownTags = new Set(providers.flatMap((p) => p.tags));
       const unsupportedTags = query.tag.filter((t) => !knownTags.has(t));
-      const appProviders = query.app ? providers.filter((provider) => provider.appId === query.app) : providers;
+      const scope = query.scope_type && query.scope_id ? { type: query.scope_type, id: query.scope_id } : undefined;
+      const appProviders = providers.filter(
+        (provider) =>
+          (!query.app || provider.appId === query.app) &&
+          (!scope || provider.scopeTypes.includes(scope.type)) &&
+          (!query.scope_tag || provider.tags.includes(query.scope_tag)),
+      );
+      if ((scope || query.scope_tag) && !appProviders.length)
+        return c.json({ code: "INVALID_SEARCH_SCOPE", message: "Search scope is unavailable" }, 400);
       const active =
         query.tag.length === 0 ? appProviders : appProviders.filter((provider) => provider.tags.some((tag) => query.tag.includes(tag)));
 
-      if (query.q.length === 0 && query.tag.length === 0 && !query.app) {
+      if (query.q.length === 0 && query.tag.length === 0 && !query.app && !scope) {
         return c.json({ query: "", count: 0, items: [], apps });
       }
 
@@ -225,7 +253,6 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
       // The same request-wide budget covers signing and provider I/O.
       const providerDeadline = AbortSignal.timeout(PROVIDER_TIMEOUT_MS);
       const fanoutSignal = AbortSignal.any([c.req.raw.signal, providerDeadline]);
-      const signingSignal = AbortSignal.any([fanoutSignal, AbortSignal.timeout(SIGNING_TIMEOUT_MS)]);
       // Guard the whole issuance batch once, then reuse the prepared signer for
       // every target. This is one Postgres check per outer search request, not
       // one check per provider.
@@ -251,17 +278,17 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
                         signer,
                         issuer: signer.issuer,
                       }),
-                    signingSignal,
+                    fanoutSignal,
                   ),
                 ),
-              { signal: signingSignal, timeoutMs: SIGNING_TIMEOUT_MS },
+              { signal: fanoutSignal, timeoutMs: PROVIDER_TIMEOUT_MS },
             ),
-            signingSignal,
+            fanoutSignal,
           );
         }
       } catch {
         log.warn("Search invocation authority unavailable", {
-          reason: signingSignal.aborted ? "signing_deadline" : "signing_guard_failed",
+          reason: fanoutSignal.aborted ? "signing_deadline" : "signing_guard_failed",
         });
         return c.json(
           { code: CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable, message: "Search invocation authority is currently unavailable" },
@@ -275,7 +302,9 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
         // Scope tags to those this provider declared. Apps no longer need
         // their own gate — the framework guarantees they only see tags
         // they understand.
-        const scopedTags = query.tag.filter((t) => provider.tags.includes(t));
+        const scopedTags = [...new Set([...(query.scope_tag ? [query.scope_tag] : []), ...query.tag])].filter((tag) =>
+          provider.tags.includes(tag),
+        );
 
         const headers = await (async () => {
           const signed = await signedInvocations?.[index];
@@ -305,6 +334,7 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
             input: {
               query: query.q,
               tags: scopedTags,
+              ...(scope ? { scope } : {}),
               limit: effectiveProviderLimit,
             },
           }),
@@ -317,7 +347,7 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
 
         const parsedBody = await readBoundedJson(res, CAPABILITY_MAX_RESULT_BYTES);
         if (!parsedBody.ok) throw new Error(`Search provider ${provider.appId} returned invalid or oversized JSON`);
-        const envelope = capabilityResultSchema(UniversalSearchDataSchema).safeParse(parsedBody.data);
+        const envelope = SearchProviderResultSchema.safeParse(parsedBody.data);
         if (!envelope.success) throw new Error(`Search provider ${provider.appId} returned an invalid capability result`);
         const results = envelope.data.data;
         const validItems: SearchItem[] = [];
@@ -399,6 +429,13 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
         items: sliced,
         apps,
         ...(unsupportedTags.length > 0 ? { unsupportedTags } : {}),
+        ...(settled.some((result) => result.status === "rejected")
+          ? {
+              failedApps: [
+                ...new Set(active.filter((_, index) => settled[index]?.status === "rejected").map((provider) => provider.appId)),
+              ],
+            }
+          : {}),
       });
     },
   );