target-supabase-sdk 0.2.0 → 0.2.1

package/src/service/index.ts

@@ -0,0 +1,173 @@
+import { scanTargetList } from "../core.api";
+import { generateResponse, type SupabaseResponse } from "../core.interface";
+import { createLogger } from "../shared/log";
+import { ServiceLifecycleStatus } from "./base.interface";
+import { getService } from "./service.api";
+import { CategoryService, type Service } from "./service.interface";
+
+export type {
+    EnumMembers,
+    FieldDefinition,
+    SchemaDefinition,
+    ServiceLifecycle,
+} from "./base.interface";
+export { ServiceLifecycleStatus } from "./base.interface";
+export type { GetApiPayload, GetServicePayload, PostApiPayload, PostServicePayload } from "./service.api";
+export {
+    apiDetailsSchema,
+    fieldDefinitionSchema,
+    getApi,
+    getApiSchema,
+    getService,
+    getServiceSchema,
+    postApi,
+    postApiSchema,
+    postService,
+    postServiceSchema,
+    schemaDefinitionSchema,
+    serviceDetailsSchema,
+    serviceLifecycleSchema,
+} from "./service.api";
+export type { Api, ApiDetails, Service, ServiceDetails } from "./service.interface";
+export { ApiMethod, CategoryApi, CategoryService } from "./service.interface";
+
+export interface DiscoverServiceInput {
+    /** {@link Service.value} */
+    value: string;
+    traceId?: string;
+}
+
+const DISCOVER_LIFECYCLE_STATUS = ServiceLifecycleStatus.ACTIVE;
+const SERVICE_LIFECYCLE_STATUS_FIELD = "details->lifecycle->>status" as const;
+
+async function lookupServicePrimary(value: string): Promise<Service | null> {
+    const response = await getService({ value, lifecycleStatus: DISCOVER_LIFECYCLE_STATUS });
+    return response.data ?? null;
+}
+
+async function lookupServiceByScan(value: string): Promise<Service | null> {
+    const { data } = await scanTargetList<Service>({
+        category: CategoryService.SERVICE,
+        orderBy: { field: "value", ascending: true },
+        maxRows: 1,
+        filterList: [
+            { field: "value", operator: "eq", value },
+            {
+                field: SERVICE_LIFECYCLE_STATUS_FIELD,
+                operator: "eq",
+                value: DISCOVER_LIFECYCLE_STATUS,
+            },
+        ],
+    });
+
+    return data?.[0] ?? null;
+}
+
+async function resolveDiscoverFailureReason(value: string): Promise<"not-found" | "not-available"> {
+    const response = await getService({ value });
+    if (response.data == null) {
+        return "not-found";
+    }
+    return "not-available";
+}
+
+/**
+ * Discover a single service by {@link Service.value}.
+ * Only returns services with `lifecycle.status === ACTIVE` (filtered at query time).
+ *
+ * Lookup: primary `getService` → fallback `scanTargetList` by value.
+ */
+export async function discoverService(input: DiscoverServiceInput): Promise<SupabaseResponse<Service>> {
+    const value = input.value.trim();
+    const logger = createLogger({
+        module: "discoverService",
+        traceId: input.traceId,
+        labels: { serviceValue: value },
+    });
+
+    if (value === "") {
+        const message = "discoverService: value must not be empty";
+        logger.warn(message, { topic: "service", data: { value: input.value } });
+        return generateResponse.error(message, undefined, "SERVICE_VALUE_REQUIRED") as SupabaseResponse<Service>;
+    }
+
+    try {
+        logger.info("开始发现服务", {
+            topic: "service",
+            data: { value, lifecycleStatus: DISCOVER_LIFECYCLE_STATUS },
+        });
+
+        let service = await lookupServicePrimary(value);
+        let source: "primary" | "scan" = "primary";
+
+        if (service == null) {
+            logger.warn("主路径未命中，尝试 catalog 扫描回退", {
+                topic: "service",
+                data: { value, step: "scan-fallback", lifecycleStatus: DISCOVER_LIFECYCLE_STATUS },
+            });
+            service = await lookupServiceByScan(value);
+            source = "scan";
+        }
+
+        if (service == null) {
+            const reason = await resolveDiscoverFailureReason(value);
+            if (reason === "not-available") {
+                const message = `Service ${value} is not available (lifecycle is not ACTIVE)`;
+                logger.warn("服务已注册但不可用", {
+                    topic: "service",
+                    data: { value, step: "not-available", lifecycleStatus: DISCOVER_LIFECYCLE_STATUS },
+                });
+                return generateResponse.error(message, undefined, "SERVICE_NOT_AVAILABLE") as SupabaseResponse<Service>;
+            }
+
+            const message = `Service not found: ${value}`;
+            logger.error("服务未发现", {
+                topic: "service",
+                data: { value, step: "not-found", tried: ["primary", "scan"] },
+            });
+            return generateResponse.error(message, undefined, "SERVICE_NOT_FOUND") as SupabaseResponse<Service>;
+        }
+
+        logger.info("服务发现成功", {
+            topic: "service",
+            data: {
+                value,
+                source,
+                serviceId: service.id,
+                lifecycleStatus: service.details.lifecycle.status,
+                apiKeyCount: service.details.apiKeys.length,
+                dependencyCount: service.details.dependencies.length,
+            },
+        });
+
+        return generateResponse.success(service);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error("服务发现失败", {
+            topic: "service",
+            data: { value, message },
+        });
+
+        let service: Service | null = null;
+        try {
+            service = await lookupServiceByScan(value);
+        } catch (fallbackError) {
+            const fallbackMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+            logger.error("扫描回退失败", {
+                topic: "service",
+                data: { value, message: fallbackMessage },
+            });
+            return generateResponse.error(message, undefined, "SERVICE_DISCOVER_FAILED") as SupabaseResponse<Service>;
+        }
+
+        if (service != null) {
+            logger.warn("主路径异常后扫描回退成功", {
+                topic: "service",
+                data: { value, serviceId: service.id, primaryError: message },
+            });
+            return generateResponse.success(service);
+        }
+
+        return generateResponse.error(message, undefined, "SERVICE_DISCOVER_FAILED") as SupabaseResponse<Service>;
+    }
+}

package/src/service/service.api.ts

@@ -0,0 +1,294 @@
+import { z } from "zod";
+import { createTarget, getPossibleTarget, getTarget, type QueryFilter, validateWithSchema } from "../core.api";
+import { type FieldDefinition, type SchemaDefinition, ServiceLifecycleStatus } from "./base.interface";
+import {
+    type Api,
+    type ApiDetails,
+    ApiMethod,
+    CategoryApi,
+    CategoryService,
+    type Service,
+    type ServiceDetails,
+} from "./service.interface";
+
+const targetIdSchema = z.string().trim().min(1);
+
+const enumMemberSchema = z.object({
+    key: z.string().trim().min(1),
+    value: z.string(),
+});
+
+const fieldPresenceSchema = z.object({
+    nullable: z.boolean(),
+    optional: z.boolean(),
+});
+
+const schemaDefinitionSchema: z.ZodType<SchemaDefinition> = z.lazy(() =>
+    z.discriminatedUnion("type", [
+        fieldPresenceSchema.extend({
+            type: z.literal("string"),
+            min: z.number().optional(),
+            max: z.number().optional(),
+            regex: z.string().optional(),
+            default: z.string().optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("number"),
+            min: z.number().optional(),
+            max: z.number().optional(),
+            default: z.number().optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("boolean"),
+            default: z.boolean().optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("unknown"),
+            default: z.unknown().optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("enum"),
+            members: z.array(enumMemberSchema).min(1),
+            defaultKey: z.string().trim().min(1).optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("object"),
+            fields: z.array(fieldDefinitionSchema),
+            default: z.record(z.unknown()).optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("array"),
+            items: schemaDefinitionSchema,
+            min: z.number().int().nonnegative().optional(),
+            max: z.number().int().nonnegative().optional(),
+            default: z.unknown().optional(),
+        }),
+    ]),
+);
+
+const fieldDefinitionSchema: z.ZodType<FieldDefinition> = z.intersection(
+    z.object({ fieldName: z.string().trim().min(1) }),
+    schemaDefinitionSchema,
+);
+
+export { fieldDefinitionSchema, schemaDefinitionSchema };
+
+export const serviceLifecycleSchema = z.object({
+    status: z.nativeEnum(ServiceLifecycleStatus),
+    activeSince: z.string().trim().min(1),
+    deprecatedAt: z.string().nullable(),
+    sunsetAt: z.string().nullable(),
+});
+
+export const apiDetailsSchema = z.object({
+    method: z.nativeEnum(ApiMethod),
+    path: z.string().trim().min(1),
+    endpoint: z.string().trim().min(1),
+    request: z.object({
+        query: z.array(fieldDefinitionSchema),
+    }),
+    response: z.object({
+        "200": z.array(fieldDefinitionSchema),
+    }),
+    manifestVersion: z.number().int().nonnegative(),
+    lifecycle: serviceLifecycleSchema,
+});
+
+export const serviceDetailsSchema = z.object({
+    manifestVersion: z.number().int().nonnegative(),
+    apiKeys: z.array(z.string().trim().min(1)),
+    dependencies: z.array(z.string().trim().min(1)).default([]),
+    lifecycle: serviceLifecycleSchema,
+});
+
+export const postApiSchema = z.object({
+    name: z.string().trim().min(1),
+    value: z.string().trim().min(1),
+    details: apiDetailsSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+});
+
+export type PostApiPayload = z.infer<typeof postApiSchema>;
+
+export const getApiSchema = z
+    .object({
+        id: targetIdSchema.optional(),
+        value: z.string().trim().min(1).optional(),
+    })
+    .refine(
+        (payload) => {
+            const hasId = payload.id != null && payload.id !== "";
+            const hasValue = payload.value != null && payload.value !== "";
+            return hasId !== hasValue;
+        },
+        { message: "Provide exactly one of id or value" },
+    );
+
+export type GetApiPayload = z.infer<typeof getApiSchema>;
+
+export const getServiceSchema = z
+    .object({
+        id: targetIdSchema.optional(),
+        value: z.string().trim().min(1).optional(),
+        /** When set, filters `details.lifecycle.status` at query time. */
+        lifecycleStatus: z.nativeEnum(ServiceLifecycleStatus).optional(),
+    })
+    .refine(
+        (payload) => {
+            const hasId = payload.id != null && payload.id !== "";
+            const hasValue = payload.value != null && payload.value !== "";
+            return hasId !== hasValue;
+        },
+        { message: "Provide exactly one of id or value" },
+    );
+
+export type GetServicePayload = z.infer<typeof getServiceSchema>;
+
+export const postServiceSchema = z.object({
+    name: z.string().trim().min(1),
+    value: z.string().trim().min(1),
+    details: serviceDetailsSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+});
+
+export type PostServicePayload = z.infer<typeof postServiceSchema>;
+
+const apiCategoryFilter = {
+    field: "category",
+    operator: "eq" as const,
+    value: CategoryApi.API,
+};
+
+const serviceCategoryFilter = {
+    field: "category",
+    operator: "eq" as const,
+    value: CategoryService.SERVICE,
+};
+
+const SERVICE_LIFECYCLE_STATUS_FIELD = "details->lifecycle->>status" as const;
+
+function buildServiceLookupFilters(payload: GetServicePayload): QueryFilter[] {
+    const filters: QueryFilter[] = [serviceCategoryFilter];
+
+    if (payload.id != null && payload.id !== "") {
+        // id path: caller adds .eq("id", id) separately
+    } else {
+        filters.push({ field: "value", operator: "eq", value: payload.value! });
+    }
+
+    if (payload.lifecycleStatus != null) {
+        filters.push({
+            field: SERVICE_LIFECYCLE_STATUS_FIELD,
+            operator: "eq",
+            value: payload.lifecycleStatus,
+        });
+    }
+
+    return filters;
+}
+
+/** Register an Api contract row (`category=api`). */
+export const postApi = validateWithSchema(
+    postApiSchema,
+    "postApiSchema",
+)(async ({ name, value, details, tagList, extra }) => {
+    return createTarget<Api, PostApiPayload>({
+        payload: { name, value, details, tagList, extra },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryApi.API,
+            tagList,
+            extra,
+            details: details as ApiDetails,
+        }),
+    });
+});
+
+/** Fetch an Api by id or by {@link Api.value} key (`category=api`). */
+export const getApi = validateWithSchema(
+    getApiSchema,
+    "getApiSchema",
+)(async (payload) => {
+    if (payload.id != null && payload.id !== "") {
+        const result = await getTarget({
+            id: payload.id,
+            filterList: [apiCategoryFilter],
+        });
+        return {
+            ...result,
+            data: result.data as Api,
+        };
+    }
+
+    const result = await getPossibleTarget({
+        filterList: [apiCategoryFilter, { field: "value", operator: "eq", value: payload.value! }],
+    });
+
+    if (result.data == null) {
+        return {
+            ...result,
+            data: undefined,
+        };
+    }
+
+    return {
+        ...result,
+        data: result.data as Api,
+    };
+});
+
+/** Fetch a Service by id or by {@link Service.value} key (`category=service`). */
+export const getService = validateWithSchema(
+    getServiceSchema,
+    "getServiceSchema",
+)(async (payload) => {
+    const filterList = buildServiceLookupFilters(payload);
+
+    if (payload.id != null && payload.id !== "") {
+        const result = await getTarget({
+            id: payload.id,
+            filterList,
+        });
+        return {
+            ...result,
+            data: result.data as Service,
+        };
+    }
+
+    const result = await getPossibleTarget({
+        filterList,
+    });
+
+    if (result.data == null) {
+        return {
+            ...result,
+            data: undefined,
+        };
+    }
+
+    return {
+        ...result,
+        data: result.data as Service,
+    };
+});
+
+/** Register a Service catalog row (`category=service`). */
+export const postService = validateWithSchema(
+    postServiceSchema,
+    "postServiceSchema",
+)(async ({ name, value, details, tagList, extra }) => {
+    return createTarget<Service, PostServicePayload>({
+        payload: { name, value, details, tagList, extra },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryService.SERVICE,
+            tagList,
+            extra,
+            details: details as ServiceDetails,
+        }),
+    });
+});

package/src/service/service.interface.ts

@@ -1,27 +1,59 @@
-import { Target } from "../core.interface";
-import { Lifecycle } from "./base.interface";
+import type { Target } from "../core.interface";
+import type { FieldDefinition, ServiceLifecycle } from "./base.interface";
 
 export interface Service extends Target {
-  /** "storage-service" 唯一键 */
-  value: string;
-  category: CategoryService;
-  details: ServiceDetails;
+    name: string;
+    /** "storage-service" 唯一键 */
+    value: string;
+    category: CategoryService;
+    details: ServiceDetails;
 }
 
 export enum CategoryService {
-  SERVICE = "service",
+    SERVICE = "service",
 }
 
-export enum ServiceStatus {
-  ACTIVE = "ACTIVE",
-  DEPRECATED = "DEPRECATED",
-  SUNSET = "SUNSET",
+export interface ServiceDetails {
+    manifestVersion: number;
+    /** 能力 Api keys */
+    apiKeys: string[];
+    /** 依赖的服务 Service keys */
+    dependencies: string[];
+    lifecycle: ServiceLifecycle;
 }
 
-export interface ServiceDetails {
-  /** 能力 Api keys */
-  apis: string[];
-  /** 依赖的服务 Service keys */
-  dependencies: string[];
-  lifecycle: Lifecycle;
+export interface Api extends Target {
+    /** "core.post.target.0" 唯一键 领域 + METHOD + content + VERSION */
+    value: string;
+    category: CategoryApi;
+    details: ApiDetails;
+}
+
+export enum CategoryApi {
+    API = "api",
+}
+
+export enum ApiMethod {
+    POST = "POST",
+    GET = "GET",
+    PUT = "PUT",
+    DELETE = "DELETE",
+}
+
+export interface ApiDetails {
+    method: ApiMethod;
+    /** /v0/core/target */
+    path: string;
+    /** out-of-box url like https://api.example.com/v0/core/target */
+    endpoint: string;
+    request: {
+        query: FieldDefinition[];
+    };
+    response: {
+        "200": FieldDefinition[];
+    };
+    manifestVersion: number;
+    lifecycle: ServiceLifecycle;
+    /** TODO contentType: e.g. application/json | application/octet-stream */
+    /** TODO auth / rate_limit / observability */
 }

package/src/shared/http/fetch-retry.ts

@@ -0,0 +1,145 @@
+import type { LoggerWithScope } from "../log/index";
+import { classifyNetworkError, formatNetworkError } from "../utils/network-error";
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Default HTTP statuses that trigger retry (429, 5xx). */
+export function isRetryableHttpStatus(status: number): boolean {
+    return status === 429 || status >= 500;
+}
+
+export type FetchInitFactory = () => RequestInit;
+
+export function requestHasBody(init: RequestInit): boolean {
+    return init.body != null;
+}
+
+export interface FetchRetryOptions {
+    label: string;
+    timeoutMs: number;
+    maxAttempts?: number;
+    retryBaseMs?: number;
+    maxBackoffMs?: number;
+    /** undici ProxyAgent or other fetch extension — typed loosely to avoid undici dependency. */
+    dispatcher?: unknown;
+    isRetryableStatus?: (status: number) => boolean;
+    /** When set, retry/success lines are logged via SDK logger. */
+    logger?: LoggerWithScope;
+    hint?: string;
+}
+
+function backoffMs(retryBaseMs: number, attempt: number, response?: Response, maxBackoffMs?: number): number {
+    const retryAfter = response?.headers.get("Retry-After");
+    if (retryAfter != null) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds) && seconds > 0) {
+            const delayMs = seconds * 1000;
+            return maxBackoffMs != null ? Math.min(delayMs, maxBackoffMs) : delayMs;
+        }
+    }
+
+    let delayMs = retryBaseMs * 2 ** (attempt - 1);
+    if (maxBackoffMs != null) {
+        delayMs = Math.min(delayMs, maxBackoffMs);
+    }
+    return delayMs;
+}
+
+async function fetchOnce(url: string, init: RequestInit, timeoutMs: number, dispatcher?: unknown): Promise<Response> {
+    const options: RequestInit & { dispatcher?: unknown } = {
+        ...init,
+        signal: AbortSignal.timeout(timeoutMs),
+    };
+    if (dispatcher != null) {
+        options.dispatcher = dispatcher;
+    }
+    return fetch(url, options);
+}
+
+export async function fetchWithRetry(
+    url: string,
+    initOrFactory: RequestInit | FetchInitFactory,
+    options: FetchRetryOptions,
+): Promise<Response> {
+    const maxAttempts = options.maxAttempts ?? 1;
+    const retryBaseMs = options.retryBaseMs ?? 2_000;
+    const isRetryableStatus = options.isRetryableStatus ?? isRetryableHttpStatus;
+    const buildInit = typeof initOrFactory === "function" ? initOrFactory : () => initOrFactory;
+
+    if (maxAttempts > 1 && typeof initOrFactory !== "function" && requestHasBody(initOrFactory)) {
+        throw new Error(`${options.label}: retry requires an init factory when request body may be consumed`);
+    }
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const response = await fetchOnce(url, buildInit(), options.timeoutMs, options.dispatcher);
+
+            if (!response.ok && isRetryableStatus(response.status) && attempt < maxAttempts) {
+                const delayMs = backoffMs(retryBaseMs, attempt, response, options.maxBackoffMs);
+                if (options.logger != null) {
+                    options.logger.warn("retrying after HTTP error", {
+                        topic: "fetch",
+                        data: {
+                            label: options.label,
+                            attempt,
+                            status: response.status,
+                            delayMs,
+                        },
+                    });
+                }
+                await sleep(delayMs);
+                continue;
+            }
+
+            if (attempt > 1 && options.logger != null) {
+                options.logger.info("request succeeded after retry", {
+                    topic: "fetch",
+                    data: { label: options.label, attempt },
+                });
+            }
+
+            return response;
+        } catch (error) {
+            const classified = classifyNetworkError(error);
+            lastError = new Error(formatNetworkError(error, options.label, { hint: options.hint }));
+
+            if (classified.retryable && attempt < maxAttempts) {
+                const delayMs = backoffMs(retryBaseMs, attempt, undefined, options.maxBackoffMs);
+                if (options.logger != null) {
+                    options.logger.warn("retrying after network error", {
+                        topic: "fetch",
+                        data: {
+                            label: options.label,
+                            attempt,
+                            maxAttempts,
+                            kind: classified.kind,
+                            code: classified.code,
+                            delayMs,
+                        },
+                    });
+                }
+                await sleep(delayMs);
+                continue;
+            }
+            throw lastError;
+        }
+    }
+
+    throw lastError ?? new Error(`${options.label}: request failed`);
+}
+
+export async function fetchBinaryWithRetry(
+    url: string,
+    init: RequestInit,
+    options: FetchRetryOptions,
+): Promise<ArrayBuffer> {
+    const response = await fetchWithRetry(url, init, options);
+    if (!response.ok) {
+        throw new Error(`${options.label}: HTTP ${response.status}`);
+    }
+    return response.arrayBuffer();
+}