@jskit-ai/http-runtime 0.1.4

package/src/shared/clientRuntime/retry.js

@@ -0,0 +1,38 @@
+const DEFAULT_RETRYABLE_CSRF_ERROR_CODES = Object.freeze(["FST_CSRF_INVALID_TOKEN", "FST_CSRF_MISSING_SECRET"]);
+
+function toUpperStringSet(values, fallback = []) {
+  const source = Array.isArray(values) ? values : fallback;
+  return new Set(
+    source
+      .map((value) =>
+        String(value || "")
+          .trim()
+          .toUpperCase()
+      )
+      .filter(Boolean)
+  );
+}
+
+function shouldRetryForCsrfFailure({
+  response,
+  method,
+  state,
+  data,
+  unsafeMethods,
+  retryableErrorCodes = DEFAULT_RETRYABLE_CSRF_ERROR_CODES
+}) {
+  const methodValue = String(method || "")
+    .trim()
+    .toUpperCase();
+  if (Number(response?.status) !== 403 || !unsafeMethods?.has(methodValue) || state?.csrfRetried) {
+    return false;
+  }
+
+  const code = String(data?.details?.code || "")
+    .trim()
+    .toUpperCase();
+  const retryableCodes = toUpperStringSet(retryableErrorCodes, DEFAULT_RETRYABLE_CSRF_ERROR_CODES);
+  return retryableCodes.has(code);
+}
+
+export { DEFAULT_RETRYABLE_CSRF_ERROR_CODES, shouldRetryForCsrfFailure };

package/src/shared/index.js

@@ -0,0 +1,30 @@
+export { createPaginationQuerySchema } from "./validators/paginationQuery.js";
+export { registerTypeBoxFormats, __testables } from "./validators/typeboxFormats.js";
+export {
+  fieldErrorsSchema,
+  apiErrorDetailsSchema,
+  apiErrorResponseSchema,
+  apiValidationErrorResponseSchema,
+  fastifyDefaultErrorResponseSchema,
+  STANDARD_ERROR_STATUS_CODES,
+  passthroughErrorResponses,
+  withStandardErrorResponses,
+  enumSchema
+} from "./validators/errorResponses.js";
+export {
+  createCursorPagedListResponseSchema,
+  createResource
+} from "./validators/resource.js";
+export { createCommand } from "./validators/command.js";
+export {
+  resolveSchemaMessages,
+  resolveFieldSchema,
+  resolveIssueField,
+  resolveMissingRequiredFields,
+  resolveIssueMessageFromSchema,
+  mapOperationIssues
+} from "./validators/operationMessages.js";
+export {
+  validateOperationSection,
+  validateOperationInput
+} from "./validators/operationValidation.js";

package/src/shared/providers/singletonApiProvider.js

@@ -0,0 +1,27 @@
+class SingletonApiProvider {
+  static bindingToken = "";
+
+  static api = null;
+
+  static providerName = "SingletonApiProvider";
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function") {
+      throw new Error(`${this.constructor.providerName} requires application singleton().`);
+    }
+
+    const bindingToken = String(this.constructor.bindingToken || "").trim();
+    if (!bindingToken) {
+      throw new Error(`${this.constructor.providerName} requires static bindingToken.`);
+    }
+    if (!this.constructor.api || typeof this.constructor.api !== "object") {
+      throw new Error(`${this.constructor.providerName} requires static api object.`);
+    }
+
+    app.singleton(bindingToken, () => this.constructor.api);
+  }
+
+  boot() {}
+}
+
+export { SingletonApiProvider };

package/src/shared/support/fieldErrors.js

@@ -0,0 +1,31 @@
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+
+function normalizeFieldErrors(value) {
+  const source = isRecord(value) ? value : {};
+  const normalized = {};
+
+  for (const [field, message] of Object.entries(source)) {
+    const normalizedField = String(field || "").trim();
+    if (!normalizedField) {
+      continue;
+    }
+    normalized[normalizedField] = String(message || "");
+  }
+
+  return normalized;
+}
+
+function resolveFieldErrors(value = null) {
+  const source = isRecord(value) ? value : {};
+  if (isRecord(source.fieldErrors)) {
+    return normalizeFieldErrors(source.fieldErrors);
+  }
+
+  if (isRecord(source.details?.fieldErrors)) {
+    return normalizeFieldErrors(source.details.fieldErrors);
+  }
+
+  return {};
+}
+
+export { isRecord, normalizeFieldErrors, resolveFieldErrors };

package/src/shared/validators/command.js

@@ -0,0 +1,34 @@
+import { asSchema } from "./schemaUtils.js";
+
+function normalizeInvalidates(value) {
+  if (!Array.isArray(value)) {
+    return Object.freeze([]);
+  }
+
+  const normalized = value
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+
+  return Object.freeze(Array.from(new Set(normalized)));
+}
+
+function createCommand({
+  input,
+  output,
+  idempotent = null,
+  invalidates = []
+} = {}) {
+  const command = {
+    input: asSchema(input, "input"),
+    output: asSchema(output, "output"),
+    invalidates: normalizeInvalidates(invalidates)
+  };
+
+  if (typeof idempotent === "boolean") {
+    command.idempotent = idempotent;
+  }
+
+  return Object.freeze(command);
+}
+
+export { createCommand };

package/src/shared/validators/errorResponses.js

@@ -0,0 +1,108 @@
+import { Type } from "@fastify/type-provider-typebox";
+
+const fieldErrorsSchema = Type.Record(Type.String(), Type.String());
+
+const apiErrorDetailsSchema = Type.Object(
+  {
+    fieldErrors: Type.Optional(fieldErrorsSchema)
+  },
+  {
+    additionalProperties: true
+  }
+);
+
+const apiErrorResponseSchema = Type.Object(
+  {
+    error: Type.String({ minLength: 1 }),
+    code: Type.Optional(Type.String({ minLength: 1 })),
+    details: Type.Optional(apiErrorDetailsSchema),
+    fieldErrors: Type.Optional(fieldErrorsSchema)
+  },
+  {
+    additionalProperties: false
+  }
+);
+
+const apiValidationErrorResponseSchema = Type.Object(
+  {
+    error: Type.String({ minLength: 1 }),
+    code: Type.Optional(Type.String({ minLength: 1 })),
+    fieldErrors: fieldErrorsSchema,
+    details: Type.Object(
+      {
+        fieldErrors: fieldErrorsSchema
+      },
+      {
+        additionalProperties: true
+      }
+    )
+  },
+  {
+    additionalProperties: false
+  }
+);
+
+const fastifyDefaultErrorResponseSchema = Type.Object(
+  {
+    statusCode: Type.Integer({ minimum: 400, maximum: 599 }),
+    error: Type.String({ minLength: 1 }),
+    message: Type.String({ minLength: 1 }),
+    code: Type.Optional(Type.String({ minLength: 1 })),
+    details: Type.Optional(Type.Unknown()),
+    fieldErrors: Type.Optional(fieldErrorsSchema)
+  },
+  {
+    additionalProperties: true
+  }
+);
+
+const STANDARD_ERROR_STATUS_CODES = [400, 401, 403, 404, 409, 422, 429, 500, 503];
+
+function passthroughErrorResponses(successResponses) {
+  return successResponses;
+}
+
+function withStandardErrorResponses(successResponses, { includeValidation400 = false } = {}) {
+  const responses = {
+    ...successResponses
+  };
+
+  for (const statusCode of STANDARD_ERROR_STATUS_CODES) {
+    if (responses[statusCode]) {
+      continue;
+    }
+
+    if (statusCode === 400 && includeValidation400) {
+      responses[statusCode] = {
+        schema: Type.Union([
+          apiValidationErrorResponseSchema,
+          apiErrorResponseSchema,
+          fastifyDefaultErrorResponseSchema
+        ])
+      };
+      continue;
+    }
+
+    responses[statusCode] = {
+      schema: Type.Union([apiErrorResponseSchema, fastifyDefaultErrorResponseSchema])
+    };
+  }
+
+  return responses;
+}
+
+function enumSchema(values) {
+  return Type.Union(values.map((value) => Type.Literal(value)));
+}
+
+export {
+  fieldErrorsSchema,
+  apiErrorDetailsSchema,
+  apiErrorResponseSchema,
+  apiValidationErrorResponseSchema,
+  fastifyDefaultErrorResponseSchema,
+  STANDARD_ERROR_STATUS_CODES,
+  passthroughErrorResponses,
+  withStandardErrorResponses,
+  enumSchema
+};

package/src/shared/validators/httpValidatorsApi.js

@@ -0,0 +1,58 @@
+import { createPaginationQuerySchema } from "./paginationQuery.js";
+import { registerTypeBoxFormats, __testables } from "./typeboxFormats.js";
+import {
+  fieldErrorsSchema,
+  apiErrorDetailsSchema,
+  apiErrorResponseSchema,
+  apiValidationErrorResponseSchema,
+  fastifyDefaultErrorResponseSchema,
+  STANDARD_ERROR_STATUS_CODES,
+  passthroughErrorResponses,
+  withStandardErrorResponses,
+  enumSchema
+} from "./errorResponses.js";
+import {
+  createCursorPagedListResponseSchema,
+  createResource
+} from "./resource.js";
+import { createCommand } from "./command.js";
+import {
+  resolveSchemaMessages,
+  resolveFieldSchema,
+  resolveIssueField,
+  resolveMissingRequiredFields,
+  resolveIssueMessageFromSchema,
+  mapOperationIssues
+} from "./operationMessages.js";
+import {
+  validateOperationSection,
+  validateOperationInput
+} from "./operationValidation.js";
+
+const HTTP_VALIDATORS_API = Object.freeze({
+  createPaginationQuerySchema,
+  registerTypeBoxFormats,
+  __testables,
+  fieldErrorsSchema,
+  apiErrorDetailsSchema,
+  apiErrorResponseSchema,
+  apiValidationErrorResponseSchema,
+  fastifyDefaultErrorResponseSchema,
+  STANDARD_ERROR_STATUS_CODES,
+  passthroughErrorResponses,
+  withStandardErrorResponses,
+  enumSchema,
+  createCursorPagedListResponseSchema,
+  createResource,
+  createCommand,
+  resolveSchemaMessages,
+  resolveFieldSchema,
+  resolveIssueField,
+  resolveMissingRequiredFields,
+  resolveIssueMessageFromSchema,
+  mapOperationIssues,
+  validateOperationSection,
+  validateOperationInput
+});
+
+export { HTTP_VALIDATORS_API };

package/src/shared/validators/operationMessages.js

@@ -0,0 +1,149 @@
+import { isRecord, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+function resolveIssueField(issue = {}) {
+  const instancePath = normalizeText(issue.instancePath);
+  if (instancePath) {
+    const segments = instancePath
+      .replace(/^\//, "")
+      .split("/")
+      .map((entry) => normalizeText(entry))
+      .filter(Boolean);
+
+    if (segments.length > 0) {
+      return segments[0];
+    }
+  }
+
+  const params = isRecord(issue.params) ? issue.params : {};
+  const missingProperty = normalizeText(params.missingProperty);
+  if (missingProperty) {
+    return missingProperty;
+  }
+
+  const requiredProperties = Array.isArray(params.requiredProperties)
+    ? params.requiredProperties
+    : [];
+  if (requiredProperties.length > 0) {
+    return normalizeText(requiredProperties[0]);
+  }
+
+  const additionalProperties = Array.isArray(params.additionalProperties)
+    ? params.additionalProperties
+    : [];
+  if (additionalProperties.length > 0) {
+    return normalizeText(additionalProperties[0]);
+  }
+
+  const additionalProperty = normalizeText(params.additionalProperty);
+  if (additionalProperty) {
+    return additionalProperty;
+  }
+
+  return "";
+}
+
+function resolveMissingRequiredFields(issue = {}) {
+  const params = isRecord(issue.params) ? issue.params : {};
+  const requiredProperties = Array.isArray(params.requiredProperties)
+    ? params.requiredProperties
+    : [];
+
+  return requiredProperties
+    .map((entry) => normalizeText(entry))
+    .filter(Boolean);
+}
+
+function resolveSchemaMessages(schema = {}) {
+  const source = isRecord(schema) ? schema : {};
+  const messages = source.messages;
+  return isRecord(messages) ? messages : {};
+}
+
+function resolveFieldSchema(schema = {}, field = "") {
+  const source = isRecord(schema) ? schema : {};
+  const properties = isRecord(source.properties) ? source.properties : {};
+  const fieldSchema = properties[field];
+  return isRecord(fieldSchema) ? fieldSchema : null;
+}
+
+function resolveIssueMessageFromSchema(field, issue, schema = {}) {
+  const keyword = normalizeText(issue?.keyword);
+
+  if (field) {
+    const fieldSchema = resolveFieldSchema(schema, field);
+    const fieldMessages = resolveSchemaMessages(fieldSchema);
+
+    const fieldKeywordMessage = normalizeText(fieldMessages[keyword]);
+    if (fieldKeywordMessage) {
+      return fieldKeywordMessage;
+    }
+
+    const fieldDefaultMessage = normalizeText(fieldMessages.default);
+    if (fieldDefaultMessage) {
+      return fieldDefaultMessage;
+    }
+  }
+
+  const schemaMessages = resolveSchemaMessages(schema);
+  const schemaKeywordMessage = normalizeText(schemaMessages[keyword]);
+  if (schemaKeywordMessage) {
+    return schemaKeywordMessage;
+  }
+
+  const schemaDefaultMessage = normalizeText(schemaMessages.default);
+  if (schemaDefaultMessage) {
+    return schemaDefaultMessage;
+  }
+
+  const issueMessage = normalizeText(issue?.message);
+  if (issueMessage) {
+    return issueMessage;
+  }
+
+  return "Invalid value.";
+}
+
+function mapOperationIssues(issues = [], schema = {}) {
+  const source = Array.isArray(issues) ? issues : [];
+  const fieldErrors = {};
+  const globalErrors = [];
+
+  for (const issue of source) {
+    const missingRequiredFields = resolveMissingRequiredFields(issue);
+    if (missingRequiredFields.length > 0) {
+      for (const field of missingRequiredFields) {
+        if (Object.hasOwn(fieldErrors, field)) {
+          continue;
+        }
+
+        fieldErrors[field] = resolveIssueMessageFromSchema(field, issue, schema);
+      }
+
+      continue;
+    }
+
+    const field = resolveIssueField(issue);
+    if (field) {
+      if (!Object.hasOwn(fieldErrors, field)) {
+        fieldErrors[field] = resolveIssueMessageFromSchema(field, issue, schema);
+      }
+      continue;
+    }
+
+    globalErrors.push(resolveIssueMessageFromSchema("", issue, schema));
+  }
+
+  return {
+    fieldErrors,
+    globalErrors
+  };
+}
+
+export {
+  resolveSchemaMessages,
+  resolveFieldSchema,
+  resolveIssueField,
+  resolveMissingRequiredFields,
+  resolveIssueMessageFromSchema,
+  mapOperationIssues
+};

package/src/shared/validators/operationValidation.js

@@ -0,0 +1,126 @@
+import { Check, Errors } from "typebox/value";
+import { mapOperationIssues } from "./operationMessages.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+
+function defaultNormalize(value) {
+  if (!isRecord(value)) {
+    return {};
+  }
+
+  return {
+    ...value
+  };
+}
+
+function resolveOperationSection(operation = {}, section = "bodyValidator") {
+  const source = isRecord(operation) ? operation : {};
+  const value = source[section];
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  return value;
+}
+
+function validateOperationSection({
+  operation = {},
+  section = "bodyValidator",
+  value,
+  context = {}
+} = {}) {
+  const sectionDefinition = resolveOperationSection(operation, section);
+  if (!sectionDefinition) {
+    return {
+      ok: true,
+      value,
+      normalized: value,
+      fieldErrors: {},
+      globalErrors: [],
+      issues: []
+    };
+  }
+
+  const schema = sectionDefinition.schema;
+  if (!isRecord(schema)) {
+    throw new TypeError(`Operation section \"${section}\" requires a schema object.`);
+  }
+
+  const normalize = typeof sectionDefinition.normalize === "function"
+    ? sectionDefinition.normalize
+    : defaultNormalize;
+
+  const normalized = normalize(value, context);
+  const issues = Check(schema, normalized) ? [] : [...Errors(schema, normalized)];
+  const mapped = mapOperationIssues(issues, schema);
+
+  return {
+    ok: issues.length < 1,
+    value: issues.length < 1 ? normalized : null,
+    normalized,
+    fieldErrors: mapped.fieldErrors,
+    globalErrors: mapped.globalErrors,
+    issues
+  };
+}
+
+function validateOperationInput({
+  operation = {},
+  input = {},
+  context = {}
+} = {}) {
+  const source = isRecord(input) ? input : {};
+  const sectionResults = {
+    paramsValidator: validateOperationSection({
+      operation,
+      section: "paramsValidator",
+      value: source.params,
+      context
+    }),
+    queryValidator: validateOperationSection({
+      operation,
+      section: "queryValidator",
+      value: source.query,
+      context
+    }),
+    bodyValidator: validateOperationSection({
+      operation,
+      section: "bodyValidator",
+      value: source.body,
+      context
+    })
+  };
+
+  const fieldErrors = {
+    ...sectionResults.paramsValidator.fieldErrors,
+    ...sectionResults.queryValidator.fieldErrors,
+    ...sectionResults.bodyValidator.fieldErrors
+  };
+
+  const globalErrors = [
+    ...sectionResults.paramsValidator.globalErrors,
+    ...sectionResults.queryValidator.globalErrors,
+    ...sectionResults.bodyValidator.globalErrors
+  ];
+
+  return {
+    ok: sectionResults.paramsValidator.ok && sectionResults.queryValidator.ok && sectionResults.bodyValidator.ok,
+    value: {
+      params: sectionResults.paramsValidator.value,
+      query: sectionResults.queryValidator.value,
+      body: sectionResults.bodyValidator.value
+    },
+    normalized: {
+      params: sectionResults.paramsValidator.normalized,
+      query: sectionResults.queryValidator.normalized,
+      body: sectionResults.bodyValidator.normalized
+    },
+    fieldErrors,
+    globalErrors,
+    sections: sectionResults
+  };
+}
+
+export {
+  validateOperationSection,
+  validateOperationInput
+};

package/src/shared/validators/paginationQuery.js

@@ -0,0 +1,32 @@
+import { Type } from "@fastify/type-provider-typebox";
+
+function createPaginationQuerySchema({
+  defaultPage = 1,
+  defaultPageSize = 10,
+  minPage = 1,
+  minPageSize = 1,
+  maxPageSize = 100
+} = {}) {
+  return Type.Object(
+    {
+      page: Type.Optional(
+        Type.Integer({
+          minimum: minPage,
+          default: defaultPage
+        })
+      ),
+      pageSize: Type.Optional(
+        Type.Integer({
+          minimum: minPageSize,
+          maximum: maxPageSize,
+          default: defaultPageSize
+        })
+      )
+    },
+    {
+      additionalProperties: false
+    }
+  );
+}
+
+export { createPaginationQuerySchema };

package/src/shared/validators/resource.js

@@ -0,0 +1,43 @@
+import { Type } from "@fastify/type-provider-typebox";
+import { asSchema } from "./schemaUtils.js";
+
+function createCursorPagedListResponseSchema(itemSchema) {
+  const normalizedItemSchema = asSchema(itemSchema, "itemSchema");
+  return Type.Object(
+    {
+      items: Type.Array(normalizedItemSchema),
+      nextCursor: Type.Union([Type.String({ minLength: 1 }), Type.Null()])
+    },
+    { additionalProperties: false }
+  );
+}
+
+function createResource({
+  record,
+  create,
+  replace,
+  patch,
+  list = null,
+  listItem = null
+} = {}) {
+  const normalizedRecordSchema = asSchema(record, "record");
+  const normalizedCreateSchema = asSchema(create, "create");
+  const normalizedReplaceSchema = asSchema(replace, "replace");
+  const normalizedPatchSchema = asSchema(patch, "patch");
+  const normalizedListItemSchema = listItem ? asSchema(listItem, "listItem") : normalizedRecordSchema;
+  const normalizedListSchema = list ? asSchema(list, "list") : createCursorPagedListResponseSchema(normalizedListItemSchema);
+
+  return Object.freeze({
+    record: normalizedRecordSchema,
+    create: normalizedCreateSchema,
+    replace: normalizedReplaceSchema,
+    patch: normalizedPatchSchema,
+    listItem: normalizedListItemSchema,
+    list: normalizedListSchema
+  });
+}
+
+export {
+  createCursorPagedListResponseSchema,
+  createResource
+};

package/src/shared/validators/schemaUtils.js

@@ -0,0 +1,9 @@
+function asSchema(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${label} must be a TypeBox schema object.`);
+  }
+
+  return value;
+}
+
+export { asSchema };