@sockethub/schemas 3.0.0-alpha.11 → 3.0.0-alpha.13

package/dist/schemas/sockethub-config.d.ts

@@ -0,0 +1,261 @@
+export declare const SockethubConfigSchema: {
+    $id: string;
+    description: string;
+    type: string;
+    required: string[];
+    additionalProperties: boolean;
+    properties: {
+        $schema: {
+            type: string;
+        };
+        examples: {
+            type: string;
+            default: boolean;
+        };
+        info: {
+            type: string;
+            default: boolean;
+        };
+        logging: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                level: {
+                    type: string;
+                    enum: string[];
+                    default: string;
+                };
+                fileLevel: {
+                    type: string;
+                    enum: string[];
+                    default: string;
+                };
+                file: {
+                    type: string;
+                    default: string;
+                };
+            };
+        };
+        platforms: {
+            type: string;
+            items: {
+                type: string;
+            };
+            default: string[];
+        };
+        packageConfig: {
+            type: string;
+            properties: {
+                "@sockethub/platform-dummy": {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        greeting: {
+                            type: string;
+                            default: string;
+                        };
+                    };
+                };
+                "@sockethub/platform-feeds": {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        connectTimeoutMs: {
+                            type: string;
+                        };
+                        allowPrivateAddresses: {
+                            type: string;
+                        };
+                        concurrency: {
+                            type: string;
+                            minimum: number;
+                        };
+                    };
+                };
+                "@sockethub/platform-irc": {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        connectTimeoutMs: {
+                            type: string;
+                        };
+                    };
+                };
+                "@sockethub/platform-xmpp": {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        connectTimeoutMs: {
+                            type: string;
+                        };
+                    };
+                };
+                "@sockethub/platform-metadata": {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        allowPrivateAddresses: {
+                            type: string;
+                        };
+                        concurrency: {
+                            type: string;
+                            minimum: number;
+                        };
+                    };
+                };
+            };
+        };
+        credentialCheck: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                reconnectIpSource: {
+                    type: string;
+                    enum: string[];
+                    default: string;
+                };
+                proxyHeader: {
+                    type: string;
+                    default: string;
+                };
+            };
+        };
+        public: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                protocol: {
+                    type: string;
+                    default: string;
+                };
+                host: {
+                    type: string;
+                    default: string;
+                };
+                port: {
+                    type: string;
+                    default: number;
+                };
+                path: {
+                    type: string;
+                    default: string;
+                };
+            };
+        };
+        rateLimiter: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                windowMs: {
+                    type: string;
+                    default: number;
+                };
+                maxRequests: {
+                    type: string;
+                    default: number;
+                };
+                blockDurationMs: {
+                    type: string;
+                    default: number;
+                };
+                maxConnectionsPerIp: {
+                    type: string;
+                    minimum: number;
+                    default: number;
+                };
+            };
+        };
+        limits: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                maxPlatformInstances: {
+                    type: string;
+                    minimum: number;
+                    default: number;
+                };
+            };
+        };
+        redis: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                url: {
+                    type: string;
+                    default: string;
+                };
+                connectTimeout: {
+                    type: string;
+                    default: number;
+                    description: string;
+                };
+                disconnectTimeout: {
+                    type: string;
+                    default: number;
+                    description: string;
+                };
+                maxRetriesPerRequest: {
+                    type: string[];
+                    default: number | null;
+                    description: string;
+                };
+            };
+        };
+        sentry: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                dsn: {
+                    type: string;
+                    default: string;
+                };
+                traceSampleRate: {
+                    type: string;
+                    default: number;
+                };
+            };
+        };
+        sockethub: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                port: {
+                    type: string;
+                    default: number;
+                };
+                host: {
+                    type: string;
+                    default: string;
+                };
+                path: {
+                    type: string;
+                    default: string;
+                };
+                cors: {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        origin: {
+                            type: string;
+                            default: string;
+                        };
+                    };
+                };
+            };
+        };
+        platformHeartbeat: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                intervalMs: {
+                    type: string;
+                    default: number;
+                };
+                timeoutMs: {
+                    type: string;
+                    default: number;
+                };
+            };
+        };
+    };
+};

package/{src/types.ts → dist/types.d.ts}

@@ -1,78 +1,58 @@
 export interface ASCollection {
-    context: string;
+    "@context": JsonLdContext;
     id?: string;
     summary: string;
     type: "collection";
     totalItems: number;
     items: Array<ActivityStream>;
 }
-
+export type JsonLdContext = Array<string>;
 export interface ActivityStream {
+    "@context": JsonLdContext;
     id?: string;
     type: string;
-    context: string;
     actor: ActivityActor;
     object?: ActivityObject;
     target?: ActivityActor;
     error?: string;
 }
-
 export interface InternalActivityStream extends ActivityStream {
     sessionSecret?: string;
 }
-
 export interface BaseActivityObject {
     id?: string;
     type: string;
 }
-
 export interface ActivityActor extends BaseActivityObject {
     id: string;
     type: string;
     name?: string;
     [key: string]: unknown;
 }
-
 export interface ActivityObject extends BaseActivityObject {
     content?: string;
     [key: string]: unknown;
 }
-
 type ErrorMsg = string | Error;
-
-export type PlatformCallback = (
-    err?: ErrorMsg,
-    data?: ActivityStream | ASCollection,
-) => void;
-
+export type PlatformCallback = (err?: ErrorMsg, data?: ActivityStream | ASCollection) => void;
 export type CallbackInterface = (err?: ErrorMsg, data?: unknown) => void;
-
 export type MiddlewareCallback = (data: ActivityStream | Error) => void;
-
 export type CompletedJobHandler = (data: ActivityStream | undefined) => void;
-
-export type PlatformSendToClient = (
-    msg: ActivityStream,
-    special?: string,
-) => void;
-
+export type PlatformSendToClient = (msg: ActivityStream, special?: string) => void;
 export type PlatformUpdateActor = (credentials: object) => Promise<void>;
-
 export interface Logger {
     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 {
     log: Logger;
     sendToClient: PlatformSendToClient;
     updateActor: PlatformUpdateActor;
 }
-
 export interface CredentialsObject {
-    context: string;
+    "@context": JsonLdContext;
     type: "credentials";
     actor: ActivityActor;
     object: {
@@ -81,7 +61,6 @@ export interface CredentialsObject {
     };
     target?: ActivityActor;
 }
-
 /**
  * Platform configuration discriminated union.
  *
@@ -100,17 +79,23 @@ export interface CredentialsObject {
  * - Example: IRC, XMPP
  */
 export type PlatformConfig = StatelessPlatformConfig | PersistentPlatformConfig;
-
 interface BasePlatformConfig {
     connectTimeoutMs?: number;
+    allowPrivateAddresses?: boolean;
 }
-
 /** Configuration for stateless platforms that start/stop per-request */
 export interface StatelessPlatformConfig extends BasePlatformConfig {
     persist: false;
     requireCredentials?: string[];
+    /**
+     * Number of jobs the platform's worker processes in parallel. Stateless
+     * platforms are shared by every session on the server, so serial
+     * processing lets one slow job (e.g. a hanging feed fetch) stall all
+     * other clients. Defaults to 10; override per-platform via
+     * `packageConfig`.
+     */
+    concurrency?: number;
 }
-
 /**
  * Configuration for persistent platforms with long-running connections.
  * These always require credentials because persistent state is actor-specific.
@@ -120,10 +105,13 @@ export interface PersistentPlatformConfig extends BasePlatformConfig {
     /** Message types requiring credentials (must be non-empty for persistent platforms) */
     requireCredentials: string[];
 }
-
 export interface PlatformSchemaStruct {
     name: string;
     version: string;
+    contextUrl: string;
+    contextVersion: string;
+    schemaVersion: string;
+    messageConstraints?: object;
     credentials?: object;
     messages?: {
         required?: string[];
@@ -133,12 +121,13 @@ export interface PlatformSchemaStruct {
             };
         };
     };
+    responses?: object;
 }
-
 export interface PlatformConstructor {
-    new (session: PlatformSession): { log: Logger };
+    new (session: PlatformSession): {
+        log: Logger;
+    };
 }
-
 /**
  * Base interface for all Sockethub platforms.
  * Platforms implement protocol-specific logic for ActivityStreams messages.
@@ -160,7 +149,6 @@ export interface PlatformInterface {
     isInitialized(): boolean;
     cleanup(cb: PlatformCallback): void;
 }
-
 /**
  * Interface for persistent platforms with long-running connections.
  *
@@ -178,15 +166,6 @@ export interface PersistentPlatformInterface extends PlatformInterface {
      */
     credentialsHash: string | undefined;
     get config(): PersistentPlatformConfig;
-    connect(
-        job: ActivityStream,
-        credentials: CredentialsObject,
-        done: PlatformCallback,
-    ): void;
-}
-
-export interface PlatformSession {
-    log: Logger;
-    sendToClient: PlatformSendToClient;
-    updateActor: PlatformUpdateActor;
+    connect(job: ActivityStream, credentials: CredentialsObject, done: PlatformCallback): void;
 }
+export {};

package/dist/validator.d.ts

@@ -0,0 +1,26 @@
+import { type Schema } from "ajv";
+import { type ValidationErrorOptions } from "./helpers/error-parser.js";
+import type { ActivityStream } from "./types.js";
+export declare function registerSystemPlatformContexts(): void;
+export declare function setValidationErrorOptions(options: ValidationErrorOptions): void;
+/**
+ * Validate a (fully-materialized) Sockethub server config object against the
+ * canonical config schema. Returns "" when valid, otherwise a human-readable
+ * error string. Used by the server at startup so a mis-typed or unknown config
+ * value — including inside a platform's `packageConfig` entry — fails loudly
+ * rather than reaching a platform wrong-typed.
+ */
+export declare function validateSockethubConfig(config: unknown): string;
+export declare function validateActivityStream(msg: ActivityStream): string;
+/**
+ * Validate an outbound platform response against that platform's `responses`
+ * schema. Returns "" when the platform has no responses schema registered (yet),
+ * so outbound validation can be adopted platform-by-platform.
+ */
+export declare function validateActivityStreamResponse(msg: ActivityStream): string;
+export declare function validateCredentials(msg: ActivityStream): string;
+export declare function validatePlatformSchema(schema: Schema): string;
+export declare function addPlatformSchema(schema: Schema, platform_type: string): void;
+export declare function getPlatformSchema(platform_type: string): import("ajv/dist/core.js").AnyValidateFunction<unknown>;
+export declare function addPlatformContext(platformId: string, platformContextUrl: string): void;
+export declare function resolvePlatformId(msg: ActivityStream): string | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sockethub/schemas",
   "description": "JSON schema files for validating Sockethub Activity Streams",
-  "version": "3.0.0-alpha.11",
+  "version": "3.0.0-alpha.13",
   "type": "module",
   "private": false,
   "author": "Nick Jennings <nick@silverbucket.net>",
@@ -12,20 +12,29 @@
   "main": "dist/index.js",
   "exports": {
     ".": {
-      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./context": {
+      "types": "./dist/context.d.ts",
+      "import": "./dist/context.js",
+      "default": "./dist/context.js"
+    },
+    "./object-types": {
+      "types": "./dist/object-types.d.ts",
+      "import": "./dist/object-types.js",
+      "default": "./dist/object-types.js"
+    },
     "./schemas/json/sockethub-config.json": {
-      "default": "./src/schemas/json/sockethub-config.json"
+      "default": "./dist/schemas/json/sockethub-config.json"
     }
   },
   "files": [
-    "src/",
     "dist/"
   ],
   "engines": {
-    "bun": ">=1.2"
+    "node": ">=20"
   },
   "keywords": [
     "sockethub",
@@ -44,7 +53,7 @@
     "@types/bun": "latest"
   },
   "scripts": {
-    "build": "bun ./scripts/export-json-schema.ts && bun build src/index.ts --outdir dist --target node --format esm --sourcemap=external",
+    "build": "bun ./scripts/export-json-schema.ts && bun ./scripts/export-canonical-assets.ts && bun build src/index.ts src/object-types.ts --outdir dist --target node --format esm --sourcemap=external && bun build src/context.ts src/activity-stream-helper.ts --outdir dist --target browser --format esm --sourcemap=external",
     "clean": "rm -rf dist",
     "clean:deps": "rm -rf node_modules"
   },
@@ -53,5 +62,6 @@
     "ajv-formats": "^2.1.1",
     "ajv-formats-draft2019": "^1.6.1"
   },
-  "gitHead": "c243fa9e76c688ce5ffcf524400b1dd27dcce615"
+  "gitHead": "864733e5b34449ef39542eceb4ff11aa308081bc",
+  "types": "./dist/index.d.ts"
 }

package/src/helpers/error-parser.ts

@@ -1,113 +0,0 @@
-import type { ErrorObject } from "ajv";
-import type { ActivityObject, ActivityStream } from "../types.js";
-import { ObjectTypesList } from "./objects.js";
-
-interface TypeBreakdown {
-    actor: Array<string>;
-    object: Array<string>;
-    target: Array<string>;
-}
-
-function parseMsg(error: ErrorObject): string {
-    let err = `${
-        error.instancePath ? error.instancePath : "activity stream"
-    }: ${error.message}`;
-    if (error.keyword === "additionalProperties") {
-        err += `: ${error.params.additionalProperty}`;
-    } else if (error.keyword === "enum") {
-        err += `: ${error.params.allowedValues.join(", ")}`;
-    }
-    return err;
-}
-
-function getTypeList(msg: ActivityStream | ActivityObject): Array<string> {
-    let types = [];
-    types.push(msg?.type);
-    for (const prop in msg) {
-        if (msg[prop]?.type) {
-            types = [...types, ...getTypeList(msg[prop])];
-        }
-    }
-    return types;
-}
-
-function getSchemaType(error: ErrorObject): string {
-    const schemaTypeRes = error.schemaPath.match(/#\/\w+\/\w+\/([\w-]+)\//);
-    return schemaTypeRes ? schemaTypeRes[1] : undefined;
-}
-
-function getErrType(error: ErrorObject): string {
-    const errTypeRes = error.instancePath.match(/\/(\w+)/);
-    return errTypeRes ? errTypeRes[1] : undefined;
-}
-
-function getPartsCount(error: ErrorObject, types: TypeBreakdown): number {
-    const schemaType = getSchemaType(error);
-    const errType = getErrType(error);
-    if (!errType) {
-        return -1;
-    }
-    if (!types[errType]) {
-        return -1;
-    }
-    if (!types[errType].includes(schemaType)) {
-        return -1;
-    }
-    const parts = error.instancePath.split("/");
-    return parts.length;
-}
-
-function getTypes(msg: ActivityStream): TypeBreakdown {
-    return {
-        actor: getTypeList(msg.actor),
-        target: getTypeList(msg.target),
-        object: getTypeList(msg.context ? msg.object : msg),
-    };
-}
-
-/**
- * Traverses the errors array from ajv, and makes a series of filtering decisions to
- * try to arrive at the most useful error.
- * @param msg
- * @param errors
- * @returns {string}
- */
-export default function getErrorMessage(
-    msg,
-    errors: Array<ErrorObject>,
-): string {
-    const types = getTypes(msg);
-    let deepest_entry = 0;
-    let highest_depth = -1;
-
-    for (let i = 0; i < errors.length; i++) {
-        const partsCount = getPartsCount(errors[i], types);
-        if (partsCount > highest_depth) {
-            highest_depth = partsCount;
-            deepest_entry = i;
-        }
-    }
-
-    return highest_depth >= 0
-        ? parseMsg(errors[deepest_entry])
-        : composeFinalError(errors[errors.length - 1]);
-}
-
-function composeFinalError(error) {
-    // if we have yet to build an error message, assume this is an invalid type value (oneOf),
-    // try to build a list of valid types
-    let msg: string;
-    if (error.keyword === "oneOf") {
-        msg =
-            `${error.instancePath}: ${error.message}: ` +
-            `${ObjectTypesList.join(", ")}`;
-    } else {
-        msg = `${
-            error.instancePath ? error.instancePath : "activity stream"
-        }: ${error.message}`;
-    }
-    if ("additionalProperty" in error.params) {
-        msg += `: ${error.params.additionalProperty}`;
-    }
-    return msg;
-}