target-supabase-sdk 0.2.3 → 0.2.4

package/src/service/index.ts

@@ -1,9 +1,6 @@
-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";
+/**
+ * Service domain public API — curated re-exports only.
+ */
 
 export type {
     EnumMembers,
@@ -12,6 +9,59 @@ export type {
     ServiceLifecycle,
 } from "./base.interface";
 export { ServiceLifecycleStatus } from "./base.interface";
+export type {
+    GetConfigPayload,
+    PostSystemRegistryConfigPayload,
+    ResetSystemRegistryConfigPayload,
+    SystemRegistrySeedSlot,
+} from "./config.api";
+export {
+    buildEmptyServiceSlots,
+    buildSystemRegistryConfigDetails,
+    DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS,
+    getConfig,
+    getConfigSchema,
+    postSystemRegistryConfig,
+    postSystemRegistryConfigSchema,
+    resetSystemRegistryConfig,
+    resetSystemRegistryConfigSchema,
+    systemRegistrySeedSlotSchema,
+} from "./config.api";
+export type { Config, ConfigDetails } from "./config.interface";
+export { CategoryConfig, TARGET_SYSTEM_REGISTRY_KEY } from "./config.interface";
+export type {
+    PatchServiceRuntimeInput,
+    RegisterServiceInput,
+    TargetSystemRegistrySlotView,
+    TargetSystemRegistryView,
+} from "./registry.service";
+export {
+    assertRegistrySlotAvailable,
+    assertRegistrySlotOwner,
+    getTargetSystemRegistry,
+    parseServiceSlot,
+    parseServiceSlots,
+    patchServiceRuntime,
+    registerService,
+    registerServiceAtStartup,
+    resolveActiveRegistryServiceId,
+    ServiceRegistryError,
+    unregisterService,
+    unregisterServiceAtShutdown,
+} from "./registry.service";
+export type {
+    ClaimRegistrySlotInput,
+    RegistrySlotGuardResult,
+    RegistrySlotRuntimeState,
+    ServiceRegistrySession,
+} from "./registry-lifecycle";
+export {
+    claimServiceRegistrySlot,
+    createClaimedRegistrySlotRuntimeState,
+    EMPTY_REGISTRY_SLOT_RUNTIME_STATE,
+    registrySlotRuntimePatchFromGuardResult,
+    runRegistrySlotGuardCheck,
+} from "./registry-lifecycle";
 export type { GetApiPayload, GetServicePayload, PostApiPayload, PostServicePayload } from "./service.api";
 export {
     apiDetailsSchema,
@@ -27,147 +77,22 @@ export {
     schemaDefinitionSchema,
     serviceDetailsSchema,
     serviceLifecycleSchema,
+    serviceNodeSnapshotSchema,
+    serviceRuntimeSchema,
 } 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>;
-    }
-}
+export type {
+    Api,
+    ApiDetails,
+    Service,
+    ServiceDetails,
+    ServiceNodeSnapshot,
+    ServiceRuntime,
+    ServiceSlot,
+} from "./service.interface";
+export { ApiMethod, CategoryApi, CategoryService, ServiceSlotStatus } from "./service.interface";
+export type { PostServiceInstanceOptions, ServiceBootstrapResult } from "./service-bootstrap";
+export {
+    createActiveServiceLifecycle,
+    defaultL3ServiceDetails,
+    postServiceInstance,
+} from "./service-bootstrap";

package/src/service/registry-lifecycle.ts

@@ -0,0 +1,144 @@
+import { deleteTarget } from "../core.api";
+import { createLogger } from "../shared/log";
+import {
+    assertRegistrySlotAvailable,
+    assertRegistrySlotOwner,
+    registerServiceAtStartup,
+    ServiceRegistryError,
+    unregisterServiceAtShutdown,
+} from "./registry.service";
+import type { Service } from "./service.interface";
+
+const LOG_TOPIC = "service-registry-lifecycle";
+
+/** Shared registry slice for L3 runtime state files (`state.json`). */
+export interface RegistrySlotRuntimeState {
+    serviceId: string | null;
+    serviceValue: string | null;
+    slotOwned: boolean | null;
+    lastSlotCheckAt: string | null;
+    lastSlotCheckError: string | null;
+}
+
+export const EMPTY_REGISTRY_SLOT_RUNTIME_STATE: RegistrySlotRuntimeState = {
+    serviceId: null,
+    serviceValue: null,
+    slotOwned: null,
+    lastSlotCheckAt: null,
+    lastSlotCheckError: null,
+};
+
+export function createClaimedRegistrySlotRuntimeState(service: Service): RegistrySlotRuntimeState {
+    return {
+        serviceId: service.id,
+        serviceValue: service.value,
+        slotOwned: true,
+        lastSlotCheckAt: null,
+        lastSlotCheckError: null,
+    };
+}
+
+export interface ClaimRegistrySlotInput {
+    serviceValue: string;
+    createInstance: () => Promise<Service>;
+    traceId?: string;
+}
+
+export interface ServiceRegistrySession {
+    service: Service;
+    /** Graceful shutdown — releases ACTIVE registry slot. */
+    release: () => Promise<void>;
+    /** Abandon orphan instance row when register never succeeded. */
+    abandon: () => Promise<void>;
+}
+
+/**
+ * Preflight → create Service instance → claim registry slot.
+ * On register failure after `createInstance`, deletes the orphan Service row.
+ */
+export async function claimServiceRegistrySlot(input: ClaimRegistrySlotInput): Promise<ServiceRegistrySession> {
+    const logger = createLogger({
+        module: "claimServiceRegistrySlot",
+        traceId: input.traceId,
+        labels: { serviceValue: input.serviceValue },
+    });
+
+    await assertRegistrySlotAvailable(input.serviceValue);
+
+    const service = await input.createInstance();
+    let registered = false;
+
+    try {
+        await registerServiceAtStartup({ service, traceId: input.traceId });
+        registered = true;
+    } catch (error) {
+        await deleteTarget({ id: service.id }).catch((deleteError: unknown) => {
+            const message = deleteError instanceof Error ? deleteError.message : String(deleteError);
+            logger.warn("Failed to delete orphan Service row after register failure", {
+                topic: LOG_TOPIC,
+                data: { serviceId: service.id, message },
+            });
+        });
+        throw error;
+    }
+
+    logger.info("registry slot claimed", {
+        topic: LOG_TOPIC,
+        data: { serviceValue: service.value, serviceId: service.id, registered },
+    });
+
+    return {
+        service,
+        release: async () => {
+            await unregisterServiceAtShutdown({ service, traceId: input.traceId });
+        },
+        abandon: async () => {
+            await deleteTarget({ id: service.id }).catch(() => undefined);
+        },
+    };
+}
+
+export interface RegistrySlotGuardResult {
+    slotOwned: boolean | null;
+    shouldShutdown: boolean;
+    error?: string;
+}
+
+/**
+ * Runtime guard step for service supervisor loops.
+ * Transient read failures soft-fail; confirmed slot loss returns `shouldShutdown: true`.
+ */
+export async function runRegistrySlotGuardCheck(input: {
+    serviceValue: string;
+    serviceId: string;
+}): Promise<RegistrySlotGuardResult> {
+    try {
+        await assertRegistrySlotOwner(input);
+        return { slotOwned: true, shouldShutdown: false };
+    } catch (error) {
+        if (error instanceof ServiceRegistryError && error.code === "REGISTRY_SLOT_LOST") {
+            return {
+                slotOwned: false,
+                shouldShutdown: true,
+                error: error.message,
+            };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            slotOwned: null,
+            shouldShutdown: false,
+            error: message,
+        };
+    }
+}
+
+export function registrySlotRuntimePatchFromGuardResult(
+    result: RegistrySlotGuardResult,
+    checkedAt: string,
+): Pick<RegistrySlotRuntimeState, "slotOwned" | "lastSlotCheckAt" | "lastSlotCheckError"> {
+    return {
+        slotOwned: result.slotOwned,
+        lastSlotCheckAt: checkedAt,
+        lastSlotCheckError: result.error ?? null,
+    };
+}