@gencow/core 0.1.28 → 0.1.29

package/src/platform-capacity-profile.ts

@@ -0,0 +1,114 @@
+export type PlatformCapacityProfileName = "prod" | "dev" | "local";
+
+export interface PlatformCapacityPreset {
+  profile: PlatformCapacityProfileName;
+  maxConcurrentRunning: number | null;
+  maxConcurrentWake: number | null;
+  maxWakeQueueMs: number;
+  minAvailableRamMB: number | null;
+  evictionThresholdMB: number | null;
+  sleepTimeoutMinutes: number;
+  sleepMaxPerCycle: number;
+  warmPoolMinIdle: number;
+  warmPoolMax: number;
+  deployCandidateReserve: number;
+}
+
+export const PLATFORM_CAPACITY_PROFILE_ENV = "GENCOW_CAPACITY_PROFILE";
+
+export const PLATFORM_CAPACITY_ENV_KEYS = [
+  PLATFORM_CAPACITY_PROFILE_ENV,
+  "MAX_CONCURRENT_RUNNING",
+  "MAX_CONCURRENT_WAKE",
+  "MAX_WAKE_QUEUE_MS",
+  "MIN_AVAILABLE_RAM_MB",
+  "WAKE_RETRY_AFTER_SEC",
+  "EVICTION_THRESHOLD_MB",
+  "GENCOW_SLEEP_TIMEOUT_MINUTES",
+  "GENCOW_SLEEP_MAX_PER_CYCLE",
+  "WARM_POOL_MIN_IDLE",
+  "WARM_POOL_MAX",
+  "DEPLOY_CANDIDATE_RESERVE",
+  "GENCOW_APP_PORT_RANGE",
+  "COWBOX_WARM_POOL_PORT_RANGE",
+] as const;
+
+export const PLATFORM_CAPACITY_PRESETS: Record<PlatformCapacityProfileName, PlatformCapacityPreset> = Object.freeze({
+  prod: Object.freeze({
+    profile: "prod",
+    maxConcurrentRunning: 600,
+    maxConcurrentWake: 20,
+    maxWakeQueueMs: 5000,
+    minAvailableRamMB: 8192,
+    evictionThresholdMB: 16384,
+    sleepTimeoutMinutes: 15,
+    sleepMaxPerCycle: 50,
+    warmPoolMinIdle: 10,
+    warmPoolMax: 650,
+    deployCandidateReserve: 40,
+  }),
+  dev: Object.freeze({
+    profile: "dev",
+    maxConcurrentRunning: 60,
+    maxConcurrentWake: 5,
+    maxWakeQueueMs: 3000,
+    minAvailableRamMB: 2048,
+    evictionThresholdMB: 4096,
+    sleepTimeoutMinutes: 10,
+    sleepMaxPerCycle: 20,
+    warmPoolMinIdle: 3,
+    warmPoolMax: 70,
+    deployCandidateReserve: 5,
+  }),
+  local: Object.freeze({
+    profile: "local",
+    maxConcurrentRunning: null,
+    maxConcurrentWake: null,
+    maxWakeQueueMs: 5000,
+    minAvailableRamMB: null,
+    evictionThresholdMB: null,
+    sleepTimeoutMinutes: 30,
+    sleepMaxPerCycle: 10,
+    warmPoolMinIdle: 3,
+    warmPoolMax: 10,
+    deployCandidateReserve: 0,
+  }),
+});
+
+function normalizeDomain(value: string | undefined): string {
+  return (value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^https?:\/\//, "")
+    .replace(/\/.*$/, "");
+}
+
+export function detectPlatformCapacityProfile(
+  env: Record<string, string | undefined> = process.env,
+): PlatformCapacityProfileName {
+  const explicit = env[PLATFORM_CAPACITY_PROFILE_ENV]?.trim().toLowerCase();
+  if (explicit) {
+    if (["prod", "production", "128gb"].includes(explicit)) return "prod";
+    if (["dev", "development", "16gb"].includes(explicit)) return "dev";
+    if (["local", "test", "disabled"].includes(explicit)) return "local";
+    throw new Error(`Invalid ${PLATFORM_CAPACITY_PROFILE_ENV}: ${explicit}. Expected prod, dev, or local.`);
+  }
+
+  const baseDomain = normalizeDomain(env.BASE_DOMAIN);
+  if (baseDomain === "gencow.dev") return "dev";
+  if (baseDomain === "gencow.app") return "prod";
+
+  const platformUrl = normalizeDomain(env.GENCOW_PLATFORM_URL);
+  if (platformUrl === "gencow.dev") return "dev";
+  if (platformUrl === "gencow.app") return "prod";
+
+  if (env.NODE_ENV === "production" && env.IS_PLATFORM === "true") return "prod";
+  return "local";
+}
+
+export function resolvePlatformCapacityPreset(
+  env: Record<string, string | undefined> = process.env,
+): PlatformCapacityPreset {
+  const profile = detectPlatformCapacityProfile(env);
+  return { ...PLATFORM_CAPACITY_PRESETS[profile] };
+}

package/src/procedure.ts

@@ -0,0 +1,283 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { GencowCtx } from "./context.js";
+
+type InferInputSchema<TSchema> = TSchema extends { "~standard": { types: { input: infer TInput } } }
+  ? TInput
+  : TSchema extends StandardSchemaV1
+    ? StandardSchemaV1.InferInput<TSchema>
+    : unknown;
+
+type InferOutputSchema<TSchema> = TSchema extends { "~standard": { types: { output: infer TOutput } } }
+  ? TOutput
+  : TSchema extends { _output: infer TOutput }
+    ? TOutput
+    : TSchema extends StandardSchemaV1
+      ? StandardSchemaV1.InferOutput<TSchema>
+      : unknown;
+
+type NextFn<TContext, TInput, TOutput> = (overrides?: {
+  context?: TContext;
+  input?: TInput;
+}) => Promise<TOutput>;
+
+export type GencowProcedureMiddleware<TContext, TInput, TOutput> = (options: {
+  context: TContext;
+  input: TInput;
+  next: NextFn<TContext, TInput, TOutput>;
+}) => Promise<TOutput> | TOutput;
+
+export type GencowProcedureHandler<TContext, TInput, TOutput> = (options: {
+  context: TContext;
+  input: TInput;
+}) => Promise<TOutput> | TOutput;
+
+export interface GencowProcedureDef<
+  TKind extends "query" | "mutation" = "query" | "mutation",
+  TContext = any,
+  TInput = unknown,
+  TOutput = unknown,
+> {
+  kind: TKind;
+  name: string;
+  /** When false (default), RPC requires an authenticated user. */
+  isPublic: boolean;
+  middlewares: readonly GencowProcedureMiddleware<TContext, TInput, TOutput>[];
+  inputSchema?: StandardSchemaV1;
+  outputSchema?: StandardSchemaV1;
+  inputValidationIndex: number;
+  outputValidationIndex: number;
+  handler: (context: TContext, input: TInput) => Promise<TOutput>;
+}
+
+export interface GencowProcedureBuilder<
+  TKind extends "query" | "mutation" = "query" | "mutation",
+  TContext = any,
+  TInput = unknown,
+  TOutput = unknown,
+> {
+  name(name: string): GencowProcedureBuilder<TKind, TContext, TInput, TOutput>;
+  /**
+   * Allow calling this procedure without authentication (like `query("x", { public: true, ... })`).
+   * Default is authenticated-only.
+   */
+  allowPublic(): GencowProcedureBuilder<TKind, TContext, TInput, TOutput>;
+  use(
+    middleware: GencowProcedureMiddleware<TContext, TInput, TOutput>,
+  ): GencowProcedureBuilder<TKind, TContext, TInput, TOutput>;
+  input<TNextSchema extends StandardSchemaV1>(
+    schema: TNextSchema,
+  ): GencowProcedureBuilder<TKind, TContext, InferInputSchema<TNextSchema>, TOutput>;
+  output<TNextSchema extends StandardSchemaV1>(
+    schema: TNextSchema,
+  ): GencowProcedureBuilder<TKind, TContext, TInput, InferOutputSchema<TNextSchema>>;
+  handler(
+    handler: GencowProcedureHandler<TContext, TInput, TOutput>,
+  ): GencowProcedureDef<TKind, TContext, TInput, TOutput>;
+}
+
+function hasStandardSchema(schema: unknown): schema is StandardSchemaV1 {
+  return (
+    !!schema &&
+    typeof schema === "object" &&
+    "~standard" in schema &&
+    !!(schema as any)["~standard"] &&
+    typeof (schema as any)["~standard"].validate === "function"
+  );
+}
+
+async function validateWithSchema<TOutput>(schema: unknown, value: unknown): Promise<TOutput> {
+  if (!schema) return value as TOutput;
+
+  if (hasStandardSchema(schema)) {
+    const result = (await schema["~standard"].validate(value)) as
+      | { value: TOutput }
+      | { issues: readonly { message: string }[] };
+    if ("issues" in result && result.issues.length > 0) {
+      throw new Error(result.issues[0]?.message ?? "Validation failed");
+    }
+    if ("value" in result) {
+      return result.value as TOutput;
+    }
+    throw new Error("Validation failed");
+  }
+
+  throw new Error("procQuery/procMutation only supports Standard Schema v1 validators");
+}
+
+function composeMiddlewares<TContext, TInput, TOutput>(
+  middlewares: Array<GencowProcedureMiddleware<TContext, TInput, TOutput>>,
+  handler: GencowProcedureHandler<TContext, TInput, TOutput>,
+  inputSchema: StandardSchemaV1 | undefined,
+  outputSchema: StandardSchemaV1 | undefined,
+  inputValidationIndex: number,
+  outputValidationIndex: number,
+): (context: TContext, input: TInput) => Promise<TOutput> {
+  return async (initialContext, initialInput) => {
+    let idx = -1;
+    const boundedInputValidationIndex = Math.min(Math.max(0, inputValidationIndex), middlewares.length);
+    const boundedOutputValidationIndex = Math.min(Math.max(0, outputValidationIndex), middlewares.length);
+
+    const run = async (currentIdx: number, context: TContext, input: TInput): Promise<TOutput> => {
+      if (currentIdx <= idx) {
+        throw new Error("next() called multiple times in the same middleware");
+      }
+      idx = currentIdx;
+      let currentInput = input;
+
+      if (currentIdx === boundedInputValidationIndex) {
+        currentInput = (await validateWithSchema(inputSchema, currentInput)) as TInput;
+      }
+
+      if (currentIdx === middlewares.length) {
+        const output = await handler({ context, input: currentInput });
+        if (currentIdx === boundedOutputValidationIndex) {
+          return await validateWithSchema<TOutput>(outputSchema, output);
+        }
+        return output;
+      }
+
+      const middleware = middlewares[currentIdx];
+      const output = await middleware({
+        context,
+        input: currentInput,
+        next: async (overrides) => {
+          return await run(
+            currentIdx + 1,
+            (overrides?.context ?? context) as TContext,
+            (overrides?.input ?? currentInput) as TInput,
+          );
+        },
+      });
+
+      if (currentIdx === boundedOutputValidationIndex) {
+        return await validateWithSchema<TOutput>(outputSchema, output);
+      }
+
+      return output;
+    };
+
+    return await run(0, initialContext, initialInput);
+  };
+}
+
+class GencowProcedureBuilderImpl<
+  TKind extends "query" | "mutation",
+  TContext = any,
+  TInput = unknown,
+  TOutput = unknown,
+> implements GencowProcedureBuilder<TKind, TContext, TInput, TOutput> {
+  constructor(
+    private readonly kind: TKind,
+    private readonly procedureName?: string,
+    private readonly middlewares: Array<GencowProcedureMiddleware<TContext, TInput, TOutput>> = [],
+    private readonly inputSchema?: StandardSchemaV1,
+    private readonly outputSchema?: StandardSchemaV1,
+    private readonly inputValidationIndex = -1,
+    private readonly outputValidationIndex = -1,
+    private readonly isPublic = false,
+  ) {}
+
+  name(name: string) {
+    return new GencowProcedureBuilderImpl<TKind, TContext, TInput, TOutput>(
+      this.kind,
+      name,
+      this.middlewares,
+      this.inputSchema,
+      this.outputSchema,
+      this.inputValidationIndex,
+      this.outputValidationIndex,
+      this.isPublic,
+    );
+  }
+
+  allowPublic() {
+    return new GencowProcedureBuilderImpl<TKind, TContext, TInput, TOutput>(
+      this.kind,
+      this.procedureName,
+      this.middlewares,
+      this.inputSchema,
+      this.outputSchema,
+      this.inputValidationIndex,
+      this.outputValidationIndex,
+      true,
+    );
+  }
+
+  use(middleware: GencowProcedureMiddleware<TContext, TInput, TOutput>) {
+    return new GencowProcedureBuilderImpl<TKind, TContext, TInput, TOutput>(
+      this.kind,
+      this.procedureName,
+      [...this.middlewares, middleware],
+      this.inputSchema,
+      this.outputSchema,
+      this.inputValidationIndex,
+      this.outputValidationIndex,
+      this.isPublic,
+    );
+  }
+
+  input<TNextSchema extends StandardSchemaV1>(schema: TNextSchema) {
+    const nextInputValidationIndex = this.middlewares.length < 0 ? 0 : this.middlewares.length;
+
+    return new GencowProcedureBuilderImpl<TKind, TContext, InferInputSchema<TNextSchema>, TOutput>(
+      this.kind,
+      this.procedureName,
+      this.middlewares as Array<GencowProcedureMiddleware<TContext, InferInputSchema<TNextSchema>, TOutput>>,
+      schema,
+      this.outputSchema,
+      nextInputValidationIndex,
+      this.outputValidationIndex,
+      this.isPublic,
+    );
+  }
+
+  output<TNextSchema extends StandardSchemaV1>(schema: TNextSchema) {
+    const nextOutputValidationIndex = this.middlewares.length < 0 ? 0 : this.middlewares.length;
+
+    return new GencowProcedureBuilderImpl<TKind, TContext, TInput, InferOutputSchema<TNextSchema>>(
+      this.kind,
+      this.procedureName,
+      this.middlewares as Array<GencowProcedureMiddleware<TContext, TInput, InferOutputSchema<TNextSchema>>>,
+      this.inputSchema,
+      schema,
+      this.inputValidationIndex,
+      nextOutputValidationIndex,
+      this.isPublic,
+    );
+  }
+
+  handler(
+    handler: GencowProcedureHandler<TContext, TInput, TOutput>,
+  ): GencowProcedureDef<TKind, TContext, TInput, TOutput> {
+    if (!this.procedureName) {
+      throw new Error("Procedure name is required. Call .name(...) before .handler(...)");
+    }
+
+    const run = composeMiddlewares(
+      this.middlewares,
+      handler,
+      this.inputSchema,
+      this.outputSchema,
+      this.inputValidationIndex,
+      this.outputValidationIndex,
+    );
+
+    return {
+      kind: this.kind,
+      name: this.procedureName,
+      isPublic: this.isPublic,
+      middlewares: [...this.middlewares],
+      inputSchema: this.inputSchema,
+      outputSchema: this.outputSchema,
+      inputValidationIndex: this.inputValidationIndex,
+      outputValidationIndex: this.outputValidationIndex,
+      handler: run,
+    };
+  }
+}
+
+export const procQuery: GencowProcedureBuilder<"query", GencowCtx> =
+  new GencowProcedureBuilderImpl<"query", GencowCtx>("query");
+
+export const procMutation: GencowProcedureBuilder<"mutation", GencowCtx> =
+  new GencowProcedureBuilderImpl<"mutation", GencowCtx>("mutation");

package/src/reactive-mutation-types.ts

@@ -0,0 +1,13 @@
+import type { InferArgs } from "./v.js";
+import type { GencowCtx } from "./context.js";
+
+export type MutationHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
+
+export interface MutationDef<TSchema = any, TReturn = any> {
+  handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+  argsSchema?: TSchema;
+  /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
+  isPublic: boolean;
+  _args?: InferArgs<TSchema>;
+  _return?: TReturn;
+}

package/src/reactive-mutation.ts

@@ -0,0 +1,115 @@
+import { type InferArgs } from "./v.js";
+import type { MutationDef, MutationHandler } from "./reactive-mutation-types.js";
+
+// ─── mutation registry (globalThis) ─────────────────────
+// globalThis shared singleton — dual-bundle safe (see analysis-dual-module-registry.md).
+
+declare global {
+  var __gencow_mutationRegistry: (MutationDef<any, any> & { name: string })[];
+}
+
+if (!globalThis.__gencow_mutationRegistry) globalThis.__gencow_mutationRegistry = [];
+
+export const mutationRegistry = globalThis.__gencow_mutationRegistry;
+
+let mutationCounter = 0;
+
+/**
+ * mutation — 데이터 변경 함수를 선언적으로 등록합니다.
+ *
+ * 3가지 호출 방식 지원 (query와 동일한 패턴 우선):
+ *
+ * @example
+ * ```typescript
+ * // ✅ 권장: query와 동일한 (name, def) 패턴
+ * mutation("tasks.create", {
+ *     args: { title: v.string() },
+ *     handler: async (ctx, args) => { ... },
+ * });
+ *
+ * // ✅ 객체 스타일 (하위 호환)
+ * mutation({
+ *     name: "tasks.create",
+ *     handler: async (ctx) => { ... },
+ * });
+ *
+ * // ⚠️ Legacy 배열 스타일 (비권장)
+ * mutation(["tasks.list"], handler, "tasks.create");
+ * ```
+ *
+ * @note invalidates 필드는 deprecated — 전달해도 무시됩니다.
+ *       리얼타임 UI 갱신에는 ctx.realtime.emit() 또는 ctx.realtime.refresh()를 사용하세요.
+ */
+export function mutation<TSchema = any, TReturn = any>(
+  nameOrInvalidatesOrDef:
+    | string
+    | string[]
+    | {
+        name?: string;
+        args?: TSchema;
+        public?: boolean;
+        invalidates?: string[];
+        handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+      },
+  handlerOrDef?:
+    | MutationHandler<InferArgs<TSchema>, TReturn>
+    | {
+        invalidates?: string[];
+        args?: TSchema;
+        public?: boolean;
+        handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+      },
+  name?: string,
+): MutationDef<TSchema, TReturn> {
+  let argsSchema: TSchema | undefined;
+  let actualHandler: MutationHandler<InferArgs<TSchema>, TReturn>;
+  let mutName: string;
+  let isPublic = false;
+
+  if (typeof nameOrInvalidatesOrDef === "string") {
+    // New primary style: mutation("name", { args?, public?, handler })
+    mutName = nameOrInvalidatesOrDef;
+    const def = handlerOrDef as {
+      args?: TSchema;
+      public?: boolean;
+      handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+    };
+    actualHandler = def.handler;
+    argsSchema = def.args;
+    isPublic = def.public === true;
+  } else if (Array.isArray(nameOrInvalidatesOrDef)) {
+    // Legacy style: mutation([...], handler, "name") — invalidates ignored
+    actualHandler = handlerOrDef as MutationHandler<InferArgs<TSchema>, TReturn>;
+    mutName = name || `mutation_${++mutationCounter}`;
+  } else {
+    // Object style: mutation({ name?, args?, public?, handler })
+    actualHandler = nameOrInvalidatesOrDef.handler;
+    argsSchema = nameOrInvalidatesOrDef.args;
+    isPublic = nameOrInvalidatesOrDef.public === true;
+    mutName =
+      nameOrInvalidatesOrDef.name ||
+      (typeof name === "string" ? name : "") ||
+      `mutation_${++mutationCounter}`;
+  }
+
+  // 이름 미지정 시 경고 — 디버깅 지원
+  if (mutName.startsWith("mutation_")) {
+    console.warn(
+      `[gencow] mutation registered without explicit name → "${mutName}". ` +
+        `Use mutation("myMutation", { handler }) for better debugging.`,
+    );
+  }
+
+  const def: MutationDef<TSchema, TReturn> & { name: string } = {
+    name: mutName,
+    handler: actualHandler,
+    argsSchema,
+    isPublic,
+  };
+  mutationRegistry.push(def);
+  return def;
+}
+
+export function getRegisteredMutations(): (MutationDef & { name: string })[] {
+  return [...mutationRegistry];
+}

package/src/reactive-query-types.ts

@@ -0,0 +1,14 @@
+import type { InferArgs } from "./v.js";
+import type { GencowCtx } from "./context.js";
+
+export type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
+
+export interface QueryDef<TSchema = any, TReturn = any> {
+  key: string;
+  handler: QueryHandler<InferArgs<TSchema>, TReturn>;
+  argsSchema?: TSchema;
+  /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
+  isPublic: boolean;
+  _args?: InferArgs<TSchema>;
+  _return?: TReturn;
+}

package/src/reactive-query.ts

@@ -0,0 +1,48 @@
+import { type InferArgs } from "./v.js";
+import type { QueryDef, QueryHandler } from "./reactive-query-types.js";
+
+// ─── query registry (globalThis) ─────────────────────────
+// globalThis shared singleton — dual-bundle safe (see analysis-dual-module-registry.md).
+
+declare global {
+  var __gencow_queryRegistry: Map<string, QueryDef<any, any>>;
+}
+
+if (!globalThis.__gencow_queryRegistry) globalThis.__gencow_queryRegistry = new Map();
+
+export const queryRegistry = globalThis.__gencow_queryRegistry;
+
+export function query<TSchema = any, TReturn = any>(
+  key: string,
+  handlerOrDef:
+    | QueryHandler<InferArgs<TSchema>, TReturn>
+    | { args?: TSchema; public?: boolean; handler: QueryHandler<InferArgs<TSchema>, TReturn> },
+): QueryDef<TSchema, TReturn> {
+  let handler: QueryHandler<InferArgs<TSchema>, TReturn>;
+  let argsSchema: TSchema | undefined;
+  let isPublic = false;
+
+  if (typeof handlerOrDef === "function") {
+    handler = handlerOrDef;
+  } else {
+    handler = handlerOrDef.handler;
+    argsSchema = handlerOrDef.args;
+    isPublic = handlerOrDef.public === true;
+  }
+
+  const def: QueryDef<TSchema, TReturn> = { key, handler, argsSchema, isPublic };
+  queryRegistry.set(key, def);
+  return def;
+}
+
+export function getQueryHandler(key: string): QueryHandler | undefined {
+  return queryRegistry.get(key)?.handler;
+}
+
+export function getQueryDef(key: string): QueryDef | undefined {
+  return queryRegistry.get(key);
+}
+
+export function getRegisteredQueries(): string[] {
+  return Array.from(queryRegistry.keys());
+}