target-supabase-sdk 0.2.15 → 0.2.16

package/src/service/index.ts

@@ -1,5 +1,6 @@
 /**
  * Service domain public API — curated re-exports only.
+ * System registry: `./registry/` (seed, claim, slot views).
  */
 
 export type {
@@ -10,68 +11,58 @@ export type {
 } 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 {
-    AppendSystemRegistrySlotsInput,
-    AppendSystemRegistrySlotsOutcome,
+    AppendSystemRegistryEmptySlotsInput,
+    AppendSystemRegistryEmptySlotsOutcome,
+    ClaimRegistrySlotInput,
     PatchServiceRuntimeInput,
+    PostSystemRegistryConfigPayload,
     RegisterServiceInput,
+    RegistrySlotGuardResult,
+    RegistrySlotRuntimeState,
     ReleasedRegistrySlot,
     ReleaseSystemRegistrySlotsByServiceIdInput,
     ReleaseSystemRegistrySlotsByServiceIdOutcome,
     ReleaseSystemRegistrySlotsInput,
     ReleaseSystemRegistrySlotsOutcome,
+    ResetSystemRegistryConfigPayload,
+    ServiceRegistrySession,
+    ServiceSlot,
+    SystemRegistrySeedSlot,
     TargetSystemRegistrySlotView,
     TargetSystemRegistryView,
-} from "./registry.service";
+} from "./registry/index";
 export {
-    appendSystemRegistrySlots,
+    appendSystemRegistryEmptySlots,
     assertRegistrySlotAvailable,
     assertRegistrySlotOwner,
+    buildEmptyServiceSlots,
+    buildSystemRegistryConfigDetails,
+    claimServiceRegistrySlot,
+    createClaimedRegistrySlotRuntimeState,
+    DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS,
+    EMPTY_REGISTRY_SLOT_RUNTIME_STATE,
     getTargetSystemRegistry,
     parseServiceSlot,
     parseServiceSlots,
     patchServiceRuntime,
+    postSystemRegistryConfig,
+    postSystemRegistryConfigSchema,
     registerService,
     registerServiceAtStartup,
+    registrySlotRuntimePatchFromGuardResult,
     releaseSystemRegistrySlots,
     releaseSystemRegistrySlotsByServiceId,
+    resetSystemRegistryConfig,
+    resetSystemRegistryConfigSchema,
     resolveActiveRegistryServiceId,
+    runRegistrySlotGuardCheck,
     ServiceRegistryError,
+    ServiceSlotStatus,
+    systemRegistrySeedSlotSchema,
+    TARGET_SYSTEM_REGISTRY_KEY,
     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";
+} from "./registry/index";
 export type { GetApiPayload, GetServicePayload, PostApiPayload, PostServicePayload } from "./service.api";
 export {
     apiDetailsSchema,
@@ -97,9 +88,8 @@ export type {
     ServiceDetails,
     ServiceNodeSnapshot,
     ServiceRuntime,
-    ServiceSlot,
 } from "./service.interface";
-export { ApiMethod, CategoryApi, CategoryService, ServiceSlotStatus } from "./service.interface";
+export { ApiMethod, CategoryApi, CategoryService } from "./service.interface";
 export type { PostServiceInstanceOptions, ServiceBootstrapResult } from "./service-bootstrap";
 export {
     createActiveServiceLifecycle,

package/src/service/registry/index.ts

@@ -0,0 +1,65 @@
+/**
+ * System service registry — curated re-exports only.
+ * Generic Config CRUD lives in `src/config/`.
+ */
+
+export type {
+    PostSystemRegistryConfigPayload,
+    ResetSystemRegistryConfigPayload,
+    SystemRegistrySeedSlot,
+} from "./registry.api";
+export {
+    buildEmptyServiceSlots,
+    buildSystemRegistryConfigDetails,
+    postSystemRegistryConfig,
+    postSystemRegistryConfigSchema,
+    resetSystemRegistryConfig,
+    resetSystemRegistryConfigSchema,
+    systemRegistrySeedSlotSchema,
+} from "./registry.api";
+export { DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS, TARGET_SYSTEM_REGISTRY_KEY } from "./registry.constant";
+export type { ServiceSlot } from "./registry.interface";
+export { ServiceSlotStatus } from "./registry.interface";
+export type {
+    AppendSystemRegistryEmptySlotsInput,
+    AppendSystemRegistryEmptySlotsOutcome,
+    PatchServiceRuntimeInput,
+    RegisterServiceInput,
+    ReleasedRegistrySlot,
+    ReleaseSystemRegistrySlotsByServiceIdInput,
+    ReleaseSystemRegistrySlotsByServiceIdOutcome,
+    ReleaseSystemRegistrySlotsInput,
+    ReleaseSystemRegistrySlotsOutcome,
+    TargetSystemRegistrySlotView,
+    TargetSystemRegistryView,
+} from "./registry.service";
+export {
+    appendSystemRegistryEmptySlots,
+    assertRegistrySlotAvailable,
+    assertRegistrySlotOwner,
+    getTargetSystemRegistry,
+    parseServiceSlot,
+    parseServiceSlots,
+    patchServiceRuntime,
+    registerService,
+    registerServiceAtStartup,
+    releaseSystemRegistrySlots,
+    releaseSystemRegistrySlotsByServiceId,
+    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";

package/src/service/{registry-lifecycle.ts → registry/registry-lifecycle.ts}

@@ -1,5 +1,6 @@
-import { deleteTarget } from "../core.api";
-import { createLogger } from "../shared/log";
+import { deleteTarget } from "../../core.api";
+import { createLogger } from "../../shared/log";
+import type { Service } from "../service.interface";
 import {
     assertRegistrySlotAvailable,
     assertRegistrySlotOwner,
@@ -7,7 +8,6 @@ import {
     ServiceRegistryError,
     unregisterServiceAtShutdown,
 } from "./registry.service";
-import type { Service } from "./service.interface";
 
 const LOG_TOPIC = "service-registry-lifecycle";
 

package/src/service/{config.api.ts → registry/registry.api.ts}

@@ -1,34 +1,16 @@
 import { z } from "zod";
+import { getConfig } from "../../config/config.api";
+import { CategoryConfig, type Config, type ConfigDetails } from "../../config/config.interface";
 import {
     createTarget,
-    getPossibleTarget,
-    getTarget,
     isOptimisticLockError,
     type QueryFilter,
     updateTargetDetails,
     validateWithSchema,
-} from "../core.api";
-import { generateResponse } from "../core.interface";
-import { CategoryConfig, type Config, type ConfigDetails, TARGET_SYSTEM_REGISTRY_KEY } from "./config.interface";
-import { type ServiceSlot, ServiceSlotStatus } from "./service.interface";
-
-const targetIdSchema = z.string().trim().min(1);
-
-export const getConfigSchema = 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 GetConfigPayload = z.infer<typeof getConfigSchema>;
+} from "../../core.api";
+import { generateResponse } from "../../core.interface";
+import { DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS, TARGET_SYSTEM_REGISTRY_KEY } from "./registry.constant";
+import { type ServiceSlot, ServiceSlotStatus } from "./registry.interface";
 
 /** One declarative EMPTY slot entry for seeding the system registry. */
 export const systemRegistrySeedSlotSchema = z.object({
@@ -53,33 +35,12 @@ export type ResetSystemRegistryConfigPayload = PostSystemRegistryConfigPayload;
 const DEFAULT_RESET_RETRY_ATTEMPTS = 5;
 const RESET_RETRY_DELAY_MS = 50;
 
-/** Default one EMPTY slot per known L3 service (override via payload or seed file). */
-export const DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS: readonly SystemRegistrySeedSlot[] = [
-    { serviceValue: "log-service" },
-    { serviceValue: "watch-service" },
-    { serviceValue: "download-service" },
-    { serviceValue: "storage-service" },
-    { serviceValue: "gc-service" },
-    { serviceValue: "upload-service" },
-    { serviceValue: "cv-service" },
-] as const;
-
 const configCategoryFilter: QueryFilter = {
     field: "category",
     operator: "eq",
     value: CategoryConfig.CONFIG,
 };
 
-function buildConfigLookupFilters(payload: GetConfigPayload): QueryFilter[] {
-    const filters: QueryFilter[] = [configCategoryFilter];
-
-    if (payload.id == null || payload.id === "") {
-        filters.push({ field: "value", operator: "eq", value: payload.value! });
-    }
-
-    return filters;
-}
-
 /** Build EMPTY {@link ServiceSlot} rows from seed entries (one slot per array item). */
 export function buildEmptyServiceSlots(seedSlots: readonly SystemRegistrySeedSlot[]): ServiceSlot[] {
     return seedSlots.map(({ serviceValue }) => ({
@@ -113,41 +74,6 @@ export function buildSystemRegistryConfigDetails(slots: readonly ServiceSlot[]):
     };
 }
 
-/** Fetch a Config by id or by {@link Config.value} key (`category=config`). */
-export const getConfig = validateWithSchema(
-    getConfigSchema,
-    "getConfigSchema",
-)(async (payload) => {
-    const filterList = buildConfigLookupFilters(payload);
-
-    if (payload.id != null && payload.id !== "") {
-        const result = await getTarget({
-            id: payload.id,
-            filterList,
-        });
-        return {
-            ...result,
-            data: result.data as Config,
-        };
-    }
-
-    const result = await getPossibleTarget({
-        filterList,
-    });
-
-    if (result.data == null) {
-        return {
-            ...result,
-            data: undefined,
-        };
-    }
-
-    return {
-        ...result,
-        data: result.data as Config,
-    };
-});
-
 /**
  * Insert the globally unique system registry Config (`category=config`,
  * `value=target-system-registry`). Rejects duplicates via `checkRedundancyFilterList`.

package/src/service/registry/registry.constant.ts

@@ -0,0 +1,17 @@
+/** Globally unique Config key for the declarative system service registry. */
+export const TARGET_SYSTEM_REGISTRY_KEY = "target-system-registry";
+
+/**
+ * Default one EMPTY slot per known L3 service.
+ * Override via `postSystemRegistryConfig` / `resetSystemRegistryConfig` payload or gc-service seed file.
+ * Replica count = how many times the same `serviceValue` appears (not a separate maxInstances field).
+ */
+export const DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS = [
+    { serviceValue: "log-service" },
+    { serviceValue: "watch-service" },
+    { serviceValue: "download-service" },
+    { serviceValue: "storage-service" },
+    { serviceValue: "gc-service" },
+    { serviceValue: "upload-service" },
+    { serviceValue: "cv-service" },
+] as const;

package/src/service/registry/registry.interface.ts

@@ -0,0 +1,16 @@
+/**
+ * Capacity slots on the system registry Config (`details.objects`).
+ * Not fields on a Service Target row — see {@link Service} in `service.interface.ts`.
+ */
+
+export enum ServiceSlotStatus {
+    EMPTY = "EMPTY",
+    ACTIVE = "ACTIVE",
+}
+
+export interface ServiceSlot {
+    serviceValue: string;
+    /** Bound Service.id when {@link ServiceSlotStatus.ACTIVE}; null when EMPTY. */
+    serviceId: string | null;
+    status: ServiceSlotStatus;
+}

package/src/service/{registry.service.ts → registry/registry.service.ts}

@@ -9,21 +9,17 @@
  *     for crashed / ungraceful exits (stale `Service.details.runtime`)
  */
 
-import { isOptimisticLockError, updateTargetDetails } from "../core.api";
-import type { Node } from "../node/node.interface";
-import { createLogger } from "../shared/log";
-import { getConfig } from "./config.api";
-import { type Config, type ConfigDetails, TARGET_SYSTEM_REGISTRY_KEY } from "./config.interface";
-import { getService } from "./service.api";
-import {
-    type Service,
-    type ServiceDetails,
-    type ServiceNodeSnapshot,
-    type ServiceSlot,
-    ServiceSlotStatus,
-} from "./service.interface";
-
-export { TARGET_SYSTEM_REGISTRY_KEY } from "./config.interface";
+import { getConfig } from "../../config/config.api";
+import type { Config, ConfigDetails } from "../../config/config.interface";
+import { isOptimisticLockError, updateTargetDetails } from "../../core.api";
+import type { Node } from "../../node/node.interface";
+import { createLogger } from "../../shared/log";
+import { getService } from "../service.api";
+import type { Service, ServiceDetails, ServiceNodeSnapshot } from "../service.interface";
+import { TARGET_SYSTEM_REGISTRY_KEY } from "./registry.constant";
+import { type ServiceSlot, ServiceSlotStatus } from "./registry.interface";
+
+export { TARGET_SYSTEM_REGISTRY_KEY } from "./registry.constant";
 
 /** `details.meta.revision` on the system registry Config — optimistic-lock token. */
 interface RegistryConfigMeta {
@@ -85,19 +81,24 @@ export interface ReleaseSystemRegistrySlotsByServiceIdOutcome {
     unchangedServiceIds: string[];
 }
 
-export interface AppendSystemRegistrySlotsInput {
-    /** Logical service keys to declare with one new EMPTY slot each when missing. */
-    serviceValues: string[];
+export interface AppendSystemRegistryEmptySlotsInput {
+    /** Logical service key (e.g. `download-service`). */
+    serviceValue: string;
+    /** How many EMPTY slots to append. Default `1`. */
+    count?: number;
     traceId?: string;
     maxAttempts?: number;
 }
 
-export interface AppendSystemRegistrySlotsOutcome {
+export interface AppendSystemRegistryEmptySlotsOutcome {
     config: Config;
-    /** Service keys that received a new EMPTY slot this run. */
-    added: string[];
-    /** Requested keys that already had at least one declared slot — no change. */
-    skipped: string[];
+    serviceValue: string;
+    /** EMPTY slots appended this run. */
+    appended: number;
+    /** Declared slot count for `serviceValue` before this run. */
+    capacityBefore: number;
+    /** Declared slot count for `serviceValue` after this run. */
+    capacityAfter: number;
 }
 
 export class ServiceRegistryError extends Error {
@@ -618,30 +619,35 @@ export async function releaseSystemRegistrySlotsByServiceId(
 }
 
 /**
- * Append EMPTY {@link ServiceSlot} rows for logical service keys not yet declared.
- * Idempotent — skips keys that already appear in `details.objects`.
+ * Append one or more EMPTY {@link ServiceSlot} rows for a given `serviceValue`.
+ *
+ * Always grows capacity (does not skip when the key is already declared).
+ * Use for replica scale-out (e.g. second `download-service` instance).
  * Does not modify existing slots or release ACTIVE bindings.
  */
-export async function appendSystemRegistrySlots(
-    input: AppendSystemRegistrySlotsInput,
-): Promise<AppendSystemRegistrySlotsOutcome> {
-    const serviceValues = [
-        ...new Set(input.serviceValues.map((value) => value.trim()).filter((value) => value !== "")),
-    ];
-    if (serviceValues.length === 0) {
-        throw new Error("[appendSystemRegistrySlots] serviceValues must not be empty");
+export async function appendSystemRegistryEmptySlots(
+    input: AppendSystemRegistryEmptySlotsInput,
+): Promise<AppendSystemRegistryEmptySlotsOutcome> {
+    const serviceValue = input.serviceValue.trim();
+    if (serviceValue === "") {
+        throw new Error("[appendSystemRegistryEmptySlots] serviceValue must not be empty");
+    }
+
+    const count = input.count ?? 1;
+    if (!Number.isInteger(count) || count < 1) {
+        throw new Error("[appendSystemRegistryEmptySlots] count must be an integer >= 1");
     }
 
     const maxAttempts = input.maxAttempts ?? DEFAULT_REGISTER_RETRY_ATTEMPTS;
     const logger = createLogger({
-        module: "appendSystemRegistrySlots",
+        module: "appendSystemRegistryEmptySlots",
         traceId: input.traceId,
-        labels: { serviceValues: serviceValues.join(",") },
+        labels: { serviceValue, count: String(count) },
     });
 
-    logger.info("开始追加 registry 槽位声明", {
+    logger.info("开始追加 EMPTY registry 槽位", {
         topic: LOG_TOPIC_REGISTRY,
-        data: { serviceValues },
+        data: { serviceValue, count },
     });
 
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
@@ -649,31 +655,16 @@ export async function appendSystemRegistrySlots(
             const config = await loadSystemRegistryConfig();
             const revision = parseRegistryRevision(config.details.meta);
             const slots = parseServiceSlots(config);
+            const capacityBefore = slots.filter((slot) => slot.serviceValue === serviceValue).length;
 
-            const added: string[] = [];
-            const skipped: string[] = [];
-            const nextSlots = [...slots];
-
-            for (const serviceValue of serviceValues) {
-                if (isServiceValueDeclared(nextSlots, serviceValue)) {
-                    skipped.push(serviceValue);
-                    continue;
-                }
-                nextSlots.push({
+            const nextSlots = [
+                ...slots,
+                ...Array.from({ length: count }, () => ({
                     serviceValue,
                     serviceId: null,
                     status: ServiceSlotStatus.EMPTY,
-                });
-                added.push(serviceValue);
-            }
-
-            if (added.length === 0) {
-                logger.info("所有 service 已声明 — 无需追加", {
-                    topic: LOG_TOPIC_REGISTRY,
-                    data: { serviceValues, skipped },
-                });
-                return { config, added, skipped: serviceValues };
-            }
+                })),
+            ];
 
             await persistSlotClaim({
                 configId: config.id,
@@ -682,33 +673,43 @@ export async function appendSystemRegistrySlots(
             });
 
             const updated = await loadSystemRegistryConfig();
-            logger.info("registry 槽位追加成功", {
+            const capacityAfter = parseServiceSlots(updated).filter(
+                (slot) => slot.serviceValue === serviceValue,
+            ).length;
+
+            logger.info("EMPTY registry 槽位追加成功", {
                 topic: LOG_TOPIC_REGISTRY,
-                data: { added, skipped, attempt, revision: revision + 1 },
+                data: { serviceValue, appended: count, capacityBefore, capacityAfter, attempt },
             });
 
-            return { config: updated, added, skipped };
+            return {
+                config: updated,
+                serviceValue,
+                appended: count,
+                capacityBefore,
+                capacityAfter,
+            };
         } catch (error) {
             if (isOptimisticLockError(error) && attempt < maxAttempts) {
                 logger.warn("registry 乐观锁冲突，重试", {
                     topic: LOG_TOPIC_REGISTRY,
-                    data: { serviceValues, attempt, maxAttempts },
+                    data: { serviceValue, count, attempt, maxAttempts },
                 });
                 await sleep(50 * attempt);
                 continue;
             }
 
             const message = error instanceof Error ? error.message : String(error);
-            logger.error("registry 槽位追加失败", {
+            logger.error("EMPTY registry 槽位追加失败", {
                 topic: LOG_TOPIC_REGISTRY,
-                data: { serviceValues, attempt, message },
+                data: { serviceValue, count, attempt, message },
             });
             throw new ServiceRegistryError(message, "REGISTRY_UPDATE_FAILED");
         }
     }
 
     throw new ServiceRegistryError(
-        "[appendSystemRegistrySlots] Optimistic lock retries exhausted",
+        "[appendSystemRegistryEmptySlots] Optimistic lock retries exhausted",
         "REGISTRY_UPDATE_FAILED",
     );
 }

package/src/service/service.interface.ts

@@ -45,18 +45,6 @@ export interface ServiceRuntime {
     nodes: ServiceNodeSnapshot[];
 }
 
-export enum ServiceSlotStatus {
-    EMPTY = "EMPTY",
-    ACTIVE = "ACTIVE",
-}
-
-export interface ServiceSlot {
-    serviceValue: string;
-    /** Bound {@link Service.id} when {@link ServiceSlotStatus.ACTIVE}; null when EMPTY. */
-    serviceId: string | null;
-    status: ServiceSlotStatus;
-}
-
 export interface Api extends Target {
     /** "core.post.target.0" 唯一键 领域 + METHOD + content + VERSION */
     value: string;