@sockethub/schemas 3.0.0-alpha.10 → 3.0.0-alpha.12

package/src/schemas/sockethub-config.ts

@@ -9,29 +9,41 @@ export const SockethubConfigSchema = {
     description: "Sockethub Config Schema",
     type: "object",
     required: ["platforms"],
+    additionalProperties: false,
     properties: {
+        $schema: {
+            type: "string",
+        },
         examples: {
+            type: "boolean",
+            default: true,
+        },
+        logging: {
             type: "object",
+            additionalProperties: false,
             properties: {
-                enabled: {
-                    type: "boolean",
-                    default: false,
+                level: {
+                    type: "string",
+                    enum: ["error", "warn", "info", "debug"],
+                    default: "info",
+                },
+                fileLevel: {
+                    type: "string",
+                    enum: ["error", "warn", "info", "debug"],
+                    default: "debug",
                 },
-                secret: {
+                file: {
                     type: "string",
-                    default: "1234567890",
+                    default: "sockethub.log",
                 },
             },
-            additionalProperties: false,
-        },
-        log_file: {
-            type: "string",
         },
         packageConfig: {
             type: "object",
             properties: {
                 "@sockethub/activity-streams": {
                     type: "object",
+                    additionalProperties: false,
                     properties: {
                         specialObjs: {
                             type: "array",
@@ -45,38 +57,37 @@ export const SockethubConfigSchema = {
                             default: true,
                         },
                     },
-                    additionalProperties: false,
                 },
                 "@sockethub/platform-dummy": {
                     type: "object",
+                    additionalProperties: false,
                     properties: {
                         greeting: {
                             type: "string",
                             default: "Hello",
                         },
                     },
-                    additionalProperties: false,
                 },
                 "@sockethub/platform-feeds": {
                     type: "object",
+                    additionalProperties: false,
                     properties: {
                         ...connectConfigPlatforms,
                     },
-                    additionalProperties: false,
                 },
                 "@sockethub/platform-irc": {
                     type: "object",
+                    additionalProperties: false,
                     properties: {
                         ...connectConfigPlatforms,
                     },
-                    additionalProperties: false,
                 },
                 "@sockethub/platform-xmpp": {
                     type: "object",
+                    additionalProperties: false,
                     properties: {
                         ...connectConfigPlatforms,
                     },
-                    additionalProperties: false,
                 },
             },
         },
@@ -85,9 +96,17 @@ export const SockethubConfigSchema = {
             items: {
                 type: "string",
             },
+            default: [
+                "@sockethub/platform-dummy",
+                "@sockethub/platform-feeds",
+                "@sockethub/platform-irc",
+                "@sockethub/platform-metadata",
+                "@sockethub/platform-xmpp",
+            ],
         },
         public: {
             type: "object",
+            additionalProperties: false,
             properties: {
                 protocol: {
                     type: "string",
@@ -106,20 +125,68 @@ export const SockethubConfigSchema = {
                     default: "/",
                 },
             },
+        },
+        rateLimiter: {
+            type: "object",
             additionalProperties: false,
+            properties: {
+                windowMs: {
+                    type: "number",
+                    default: 1000,
+                },
+                maxRequests: {
+                    type: "number",
+                    default: 100,
+                },
+                blockDurationMs: {
+                    type: "number",
+                    default: 5000,
+                },
+            },
         },
         redis: {
             type: "object",
+            additionalProperties: false,
             properties: {
                 url: {
                     type: "string",
                     default: "redis://127.0.0.1:6379",
                 },
+                connectTimeout: {
+                    type: "number",
+                    default: 10000,
+                    description: "Connection timeout in milliseconds",
+                },
+                disconnectTimeout: {
+                    type: "number",
+                    default: 5000,
+                    description: "Disconnect timeout in milliseconds",
+                },
+                maxRetriesPerRequest: {
+                    type: ["number", "null"],
+                    default: null as number | null,
+                    description:
+                        "Maximum number of retries per request (null for BullMQ default)",
+                },
             },
+        },
+        sentry: {
+            type: "object",
             additionalProperties: false,
+            properties: {
+                dsn: {
+                    type: "string",
+                    default: "",
+                },
+                traceSampleRate: {
+                    type: "number",
+                    default: 1.0,
+                },
+            },
         },
         sockethub: {
             type: "object",
+            additionalProperties: false,
             properties: {
                 port: {
                     type: "number",
@@ -134,7 +201,20 @@ export const SockethubConfigSchema = {
                     default: "/sockethub",
                 },
             },
+        },
+        platformHeartbeat: {
+            type: "object",
             additionalProperties: false,
+            properties: {
+                intervalMs: {
+                    type: "number",
+                    default: 5000,
+                },
+                timeoutMs: {
+                    type: "number",
+                    default: 15000,
+                },
+            },
         },
     },
 };

package/src/types/ajv-formats-draft2019.d.ts

@@ -0,0 +1,5 @@
+declare module "ajv-formats-draft2019" {
+    import type Ajv from "ajv";
+    const addFormats: (ajv: Ajv) => void;
+    export default addFormats;
+}

package/src/types.ts

@@ -1,5 +1,5 @@
 export interface ASCollection {
-    context: string;
+    "@context": JsonLdContext;
     id?: string;
     summary: string;
     type: "collection";
@@ -7,10 +7,13 @@ export interface ASCollection {
     items: Array<ActivityStream>;
 }
 
+export type JsonLdContext = Array<string>;
+
 export interface ActivityStream {
+    "@context": JsonLdContext;
     id?: string;
     type: string;
-    context: string;
+    platform?: string;
     actor: ActivityActor;
     object?: ActivityObject;
     target?: ActivityActor;
@@ -59,19 +62,20 @@ export type PlatformSendToClient = (
 export type PlatformUpdateActor = (credentials: object) => Promise<void>;
 
 export interface Logger {
-    // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-    // biome-ignore lint/style/useShorthandFunctionType: <explanation>
-    (msg: string, data?: any): void;
+    error(message: string, meta?: object): void;
+    warn(message: string, meta?: object): void;
+    info(message: string, meta?: object): void;
+    debug(message: string, meta?: object): void;
 }
 
 export interface PlatformSession {
-    debug: Logger;
+    log: Logger;
     sendToClient: PlatformSendToClient;
     updateActor: PlatformUpdateActor;
 }
 
 export interface CredentialsObject {
-    context: string;
+    "@context": JsonLdContext;
     type: "credentials";
     actor: ActivityActor;
     object: {
@@ -118,13 +122,15 @@ export interface PersistentPlatformConfig extends BasePlatformConfig {
     persist: true;
     /** Message types requiring credentials (must be non-empty for persistent platforms) */
     requireCredentials: string[];
-    /** Whether the platform has completed initialization */
-    initialized: boolean;
 }
 
 export interface PlatformSchemaStruct {
     name: string;
     version: string;
+    contextUrl: string;
+    contextVersion: string;
+    schemaVersion: string;
+    messageConstraints?: object;
     credentials?: object;
     messages?: {
         required?: string[];
@@ -137,7 +143,7 @@ export interface PlatformSchemaStruct {
 }
 
 export interface PlatformConstructor {
-    new (session: PlatformSession): { debug: Logger };
+    new (session: PlatformSession): { log: Logger };
 }
 
 /**
@@ -145,9 +151,20 @@ export interface PlatformConstructor {
  * Platforms implement protocol-specific logic for ActivityStreams messages.
  */
 export interface PlatformInterface {
-    debug: Logger;
     get config(): PlatformConfig;
     get schema(): PlatformSchemaStruct;
+    /**
+     * Returns whether the platform is ready to handle jobs.
+     *
+     * For persistent platforms: Returns true once the initial connection succeeds.
+     * During temporary network interruptions with automatic reconnection, should
+     * remain true to allow queued jobs to retry rather than fail.
+     *
+     * For stateless platforms: Can always return true since they have no connection state.
+     *
+     * @returns true if the platform can process jobs, false otherwise
+     */
+    isInitialized(): boolean;
     cleanup(cb: PlatformCallback): void;
 }
 
@@ -176,7 +193,7 @@ export interface PersistentPlatformInterface extends PlatformInterface {
 }
 
 export interface PlatformSession {
-    debug: Logger;
+    log: Logger;
     sendToClient: PlatformSendToClient;
     updateActor: PlatformUpdateActor;
 }

package/src/validator.ts

@@ -1,39 +1,82 @@
 import Ajv, { type Schema } from "ajv";
 import addFormats from "ajv-formats";
 import additionsFormats2019 from "ajv-formats-draft2019";
-import debug from "debug";
-import getErrorMessage from "./helpers/error-parser.js";
+import {
+    ERROR_PLATFORM_CONTEXT_URL,
+    ERROR_PLATFORM_ID,
+    getCredentialsSchemaIdByContextUrl,
+    getPlatformIdByContextUrl,
+    getSchemaIdByContextUrl,
+    INTERNAL_PLATFORM_CONTEXT_URL,
+    INTERNAL_PLATFORM_ID,
+    registerPlatformContext,
+    resolvePlatformContextUrl,
+} from "./context.js";
+import getErrorMessage, {
+    type ValidationErrorOptions,
+} from "./helpers/error-parser.js";
 import { ActivityObjectSchema } from "./schemas/activity-object.js";
 import { ActivityStreamSchema } from "./schemas/activity-stream.js";
 import { PlatformSchema } from "./schemas/platform.js";
-import type { ActivityStream } from "./types.js";
+import type { ActivityObject, ActivityStream } from "./types.js";
 
 const ajv = new Ajv({ strictTypes: false, allErrors: true });
-addFormats(ajv);
-additionsFormats2019(ajv);
+addFormats(ajv as unknown as Parameters<typeof addFormats>[0]);
+additionsFormats2019(ajv as unknown as Ajv);
 
-interface SchemasDict {
-    string?: Schema;
-}
+type SchemasDict = Record<string, Schema>;
 
-const log = debug("sockethub:schemas:validator");
 const schemaURL = "https://sockethub.org/schemas/v0";
 const schemas: SchemasDict = {};
+let validationErrorOptions: ValidationErrorOptions = {};
+let systemContextsRegistered = false;
 
 schemas[`${schemaURL}/activity-stream`] = ActivityStreamSchema;
 schemas[`${schemaURL}/activity-object`] = ActivityObjectSchema;
 
 for (const uri in schemas) {
-    log(`registering schema ${uri}`);
     ajv.addSchema(schemas[uri], uri);
 }
 
+function registerSystemContext(platformId: string, contextUrl: string): void {
+    registerPlatformContext(
+        platformId,
+        contextUrl,
+        `${schemaURL}/context/${platformId}/messages`,
+        `${schemaURL}/context/${platformId}/credentials`,
+    );
+
+    const messageSchemaRef = `${schemaURL}/context/${platformId}/messages`;
+    if (!ajv.getSchema(messageSchemaRef)) {
+        ajv.addSchema({}, messageSchemaRef);
+    }
+
+    const credentialsSchemaRef = `${schemaURL}/context/${platformId}/credentials`;
+    if (!ajv.getSchema(credentialsSchemaRef)) {
+        ajv.addSchema({}, credentialsSchemaRef);
+    }
+}
+
+export function registerSystemPlatformContexts(): void {
+    if (systemContextsRegistered) {
+        return;
+    }
+    registerSystemContext(ERROR_PLATFORM_ID, ERROR_PLATFORM_CONTEXT_URL);
+    registerSystemContext(INTERNAL_PLATFORM_ID, INTERNAL_PLATFORM_CONTEXT_URL);
+    systemContextsRegistered = true;
+}
+
+registerSystemPlatformContexts();
+
 function handleValidation(
     schemaRef: string,
-    msg: ActivityStream,
+    msg: ActivityStream | ActivityObject,
     isObject = false,
 ): string {
     const validator = ajv.getSchema(schemaRef);
+    if (!validator) {
+        return `schema ${schemaRef} not found`;
+    }
     let result: boolean | Promise<unknown>;
     if (isObject) {
         result = validator({ object: msg });
@@ -41,37 +84,81 @@ function handleValidation(
         result = validator(msg);
     }
     if (!result) {
-        let errorMessage = getErrorMessage(msg, validator.errors);
-        if (msg.context) {
-            errorMessage = `[${msg.context}] ${errorMessage}`;
+        let errorMessage = getErrorMessage(
+            msg,
+            validator.errors,
+            validationErrorOptions,
+        );
+        if (Array.isArray((msg as ActivityStream)["@context"])) {
+            const platformContextUrl = resolvePlatformContextUrl(
+                msg as ActivityStream,
+            );
+            if (platformContextUrl) {
+                const platformId =
+                    getPlatformIdByContextUrl(platformContextUrl);
+                if (platformId) {
+                    errorMessage = `[${platformId}] ${errorMessage}`;
+                }
+            }
         }
         return errorMessage;
     }
     return "";
 }
 
-export function validateActivityObject(msg: ActivityStream): string {
+export function setValidationErrorOptions(
+    options: ValidationErrorOptions,
+): void {
+    validationErrorOptions = { ...validationErrorOptions, ...options };
+}
+
+export function validateActivityObject(msg: ActivityObject): string {
     return handleValidation(`${schemaURL}/activity-object`, msg, true);
 }
 
 export function validateActivityStream(msg: ActivityStream): string {
-    return handleValidation(`${schemaURL}/activity-stream`, msg);
+    const streamValidationError = handleValidation(
+        `${schemaURL}/activity-stream`,
+        msg,
+    );
+    if (streamValidationError) {
+        return streamValidationError;
+    }
+    const platformContextUrl = resolvePlatformContextUrl(msg);
+    if (!platformContextUrl) {
+        return "activity streams must have exactly one registered platform context URL in @context";
+    }
+    const schemaId = getSchemaIdByContextUrl(platformContextUrl);
+    if (!schemaId) {
+        return `platform context URL ${platformContextUrl} does not have a registered message schema`;
+    }
+    return handleValidation(schemaId, msg);
 }
 
 export function validateCredentials(msg: ActivityStream): string {
-    if (!msg.context) {
-        return "credential activity streams must have a context set";
+    if (!Array.isArray(msg["@context"])) {
+        return "credential activity streams must have an @context set";
     }
     if (msg.type !== "credentials") {
         return "credential activity streams must have credentials set as type";
     }
-    log(
-        `validating credentials against ${schemaURL}/context/${msg.context}/credentials`,
-    );
-    return handleValidation(
-        `${schemaURL}/context/${msg.context}/credentials`,
+    const streamValidationError = handleValidation(
+        `${schemaURL}/activity-stream`,
         msg,
     );
+    if (streamValidationError) {
+        return streamValidationError;
+    }
+    const platformContextUrl = resolvePlatformContextUrl(msg);
+    if (!platformContextUrl) {
+        return "credential activity streams must have exactly one registered platform context URL in @context";
+    }
+    const credentialsSchemaId =
+        getCredentialsSchemaIdByContextUrl(platformContextUrl);
+    if (!credentialsSchemaId) {
+        return `platform context URL ${platformContextUrl} does not have a registered credentials schema`;
+    }
+    return handleValidation(credentialsSchemaId, msg);
 }
 
 export function validatePlatformSchema(schema: Schema): string {
@@ -85,10 +172,36 @@ export function validatePlatformSchema(schema: Schema): string {
 }
 
 export function addPlatformSchema(schema: Schema, platform_type: string) {
-    log(`registering schema ${schemaURL}/context/${platform_type}`);
-    ajv.addSchema(schema, `${schemaURL}/context/${platform_type}`);
+    const schemaRef = `${schemaURL}/context/${platform_type}`;
+    if (!ajv.getSchema(schemaRef)) {
+        ajv.addSchema(schema, schemaRef);
+    }
 }
 
 export function getPlatformSchema(platform_type: string) {
     return ajv.getSchema(`${schemaURL}/context/${platform_type}`);
 }
+
+export function addPlatformContext(
+    platformId: string,
+    platformContextUrl: string,
+) {
+    registerPlatformContext(
+        platformId,
+        platformContextUrl,
+        `${schemaURL}/context/${platformId}/messages`,
+        `${schemaURL}/context/${platformId}/credentials`,
+    );
+}
+
+export function resolvePlatformId(msg: ActivityStream): string | null {
+    const platformContextUrl = resolvePlatformContextUrl(msg);
+    if (platformContextUrl) {
+        const id = getPlatformIdByContextUrl(platformContextUrl);
+        if (id) return id;
+    }
+    if (typeof msg.platform === "string" && msg.platform) {
+        return msg.platform;
+    }
+    return null;
+}