0z2i6v3u5t 1.0.0

package/src/classes/server.ts

@@ -0,0 +1,251 @@
+import { EventEmitter } from "events";
+import { api, config } from "../index";
+import { log, ActionheroLogLevel } from "../modules/log";
+import { ActionProcessor } from "./actionProcessor";
+import { Connection } from "./connection";
+
+interface ServerConfig {
+  [key: string]: any;
+}
+
+/**
+ * Create a new Actionhero Server. The required properties of an server. These can be defined statically (this.name) or as methods which return a value.
+ */
+export abstract class Server extends EventEmitter {
+  /**The name & type of the server. */
+  type: string;
+  /**What connection verbs can connections of this type use? */
+  verbs?: Array<string>;
+  /**Shorthand for `api.config[this.type]` */
+  config?: ServerConfig;
+  options?: {
+    [key: string]: any;
+  };
+  /** attributes of the server */
+  attributes: {
+    [key: string]: any;
+  };
+  /**Can connections of this server use the chat system? */
+  canChat: boolean;
+  /**Should we log every new connection? */
+  logConnections: boolean;
+  /**Should we log when a connection disconnects/exits? */
+  logExits: boolean;
+  /**Should every new connection of this server type receive the welcome message */
+  sendWelcomeMessage: boolean;
+  /**Methods described by the server to apply to each connection (like connection.setHeader for web connections) */
+  connectionCustomMethods: {
+    [key: string]: Function;
+  };
+  /**A place to store the actually server object you create */
+  server?: any;
+
+  constructor() {
+    super();
+
+    this.options = {};
+    this.attributes = {};
+    this.config = {}; // will be applied by the initializer
+    this.connectionCustomMethods = {};
+
+    this.canChat = this.canChat ?? true;
+    this.logExits = this.logExits ?? true;
+    this.sendWelcomeMessage = this.sendWelcomeMessage ?? true;
+    this.logConnections = this.logConnections ?? true;
+    this.verbs = this.verbs ?? [];
+  }
+
+  /**
+   * Event called when a formal new connection is created for this server type.  This is a response to calling Actionhero.Server#buildConnection
+   *
+   * @event Actionhero.Server#connection
+   */
+
+  /**
+   * Event called when a an action is complete for a connection created by this server.  You may want to send a response to the client as a response to this event.
+   *
+   * @event Actionhero.Server#actionComplete
+   * @property {object} data - The same data from the Action.  Includes the connection, response, etc.
+   */
+
+  /**
+   * Method run as part of the `initialize` lifecycle of your server.  Usually configures the server.
+   */
+  abstract initialize(): Promise<void>;
+
+  /**
+   * Method run as part of the `start` lifecycle of your server.  Usually boots the server (listens on port, etc).
+   */
+  abstract start(): Promise<void>;
+
+  /**
+   * Method run as part of the `stop` lifecycle of your server.  Usually configures the server (disconnects from port, etc).
+   */
+  abstract stop(): Promise<void>;
+
+  /**
+   * Must be defined explaining how to send a message to an individual connection.
+   */
+  abstract sendMessage(
+    connection: Connection,
+    message: string | object | Array<any>,
+    messageId?: string,
+  ): Promise<void>;
+
+  /**
+   * Must be defined explaining how to send a file to an individual connection.  Might be a noop for some connection types.
+   */
+  abstract sendFile(
+    connection: Connection,
+    error: NodeJS.ErrnoException,
+    fileStream: any,
+    mime: string,
+    length: number,
+    lastModified: Date,
+  ): Promise<void>;
+
+  /**An optional message to send to clients when they disconnect */
+  async goodbye?(connection: Connection): Promise<void>;
+
+  validate() {
+    if (!this.type) {
+      throw new Error("type is required for this server");
+    }
+
+    (
+      [
+        "start",
+        "stop",
+        "sendFile", // connection, error, fileStream, mime, length, lastModified
+        "sendMessage", // connection, message
+        "goodbye",
+      ] as const
+    ).forEach((method) => {
+      if (!this[method] || typeof this[method] !== "function") {
+        throw new Error(
+          `${method} is a required method for the server \`${this.type}\``,
+        );
+      }
+    });
+  }
+
+  /**
+   *   * Build a the Actionhero.Connection from the raw parts provided by the server.
+   * ```js
+   *this.buildConnection({
+   *  rawConnection: {
+   *    req: req,
+   *    res: res,
+   *    params: {},
+   *    method: method,
+   *    cookies: cookies,
+   *    responseHeaders: responseHeaders,
+   *    responseHttpCode: responseHttpCode,
+   *    parsedURL: parsedURL
+   *  },
+   *  id: fingerprint + '-' + uuid.v4(),
+   *  fingerprint: fingerprint,
+   *  remoteAddress: remoteIP,
+   *  remotePort: remotePort
+   *})
+   * ```
+   */
+  async buildConnection(data: { [key: string]: any }) {
+    const details = {
+      type: this.type,
+      id: data.id,
+      remotePort: data.remotePort,
+      remoteIP: data.remoteAddress,
+      rawConnection: data.rawConnection,
+      messageId: data.messageId,
+      canChat: this.attributes.canChat ?? null,
+      fingerprint: data.fingerprint ?? null,
+    };
+
+    const connection = await Connection.createAsync(details);
+
+    connection.sendMessage = async (message) => {
+      this.sendMessage(connection, message);
+    };
+
+    connection.sendFile = async (path) => {
+      connection.params.file = path;
+      this.processFile(connection);
+    };
+
+    this.emit("connection", connection);
+
+    if (this.attributes.logConnections === true) {
+      this.log("new connection", "info", { to: connection.remoteIP });
+    }
+
+    if (this.attributes.sendWelcomeMessage === true) {
+      connection.sendMessage({
+        welcome: config.general.welcomeMessage,
+        context: "api",
+      });
+    }
+
+    if (typeof this.attributes.sendWelcomeMessage === "number") {
+      setTimeout(() => {
+        try {
+          connection.sendMessage({
+            welcome: config.general.welcomeMessage,
+            context: "api",
+          });
+        } catch (e) {
+          this.log(e, "error");
+        }
+      }, this.attributes.sendWelcomeMessage);
+    }
+  }
+
+  /**
+   * When a connection has called an Action command, and all properties are set.  Connection should have `params.action` set at least.
+   * on(event: 'actionComplete', cb: (data: object) => void): this;
+   */
+  async processAction(connection: Connection) {
+    const actionProcessor = new ActionProcessor(connection);
+    const data = await actionProcessor.processAction();
+    this.emit("actionComplete", data);
+  }
+
+  /**
+   * When a connection has called an File command, and all properties are set.  Connection should have `params.file` set at least.  Will eventually call Actionhero.Server#sendFile.
+   */
+  async processFile(connection: Connection) {
+    const results = await api.staticFile.get(connection);
+
+    this.sendFile(
+      results.connection,
+      results.error,
+      results.fileStream,
+      results.mime,
+      results.length,
+      results.lastModified,
+    );
+  }
+
+  /**
+   * Enumerate the connections for this server type on this server.
+   */
+  connections(): Array<Connection> {
+    const connections = [];
+
+    for (const i in api.connections.connections) {
+      const connection = api.connections.connections[i];
+      if (connection.type === this.type) {
+        connections.push(connection);
+      }
+    }
+
+    return connections;
+  }
+
+  /**
+   * Log a message from this server type.  A wrapper around log() with a server prefix.
+   */
+  log(message: string, severity?: ActionheroLogLevel, data?: any) {
+    log(`[server: ${this.type}] ${message}`, severity, data);
+  }
+}

package/src/classes/task.ts

@@ -0,0 +1,87 @@
+import { Inputs } from "./inputs";
+import { Plugin, Worker } from "node-resque";
+
+/**
+ * Create a new Actionhero Task. The required properties of an task. These can be defined statically (this.name) or as methods which return a value.
+ * ```js
+ * import { Task, api, log } from "actionhero"
+ *
+ * export default class SayHello extends Task {
+ *  constructor () {
+ *   super()
+ *    this.name = 'sayHello'
+ *    this.description = 'I say Hello every minute'
+ *    this.frequency = (60 * 1000)
+ *  }
+ *  async run (data, worker) {
+ *    log('Hello!')
+ *  }
+ * }
+ * ```
+ */
+export abstract class Task {
+  /**The name of the Task */
+  name: string;
+  /**The description of the Task (default this.name) */
+  description: string;
+  /**The default queue to run this Task on (default: 'default') */
+  queue: string;
+  /**How often to run this Task, in ms.  0 is non-recurring. (default: 0) */
+  frequency?: number;
+  /**The inputs of the Task (default: {}) */
+  inputs?: Inputs;
+  /**The Middleware specific to this Task (default: []).  Middleware is described by the string names of the middleware */
+  middleware?: Array<string>;
+  /**Plugins from node-resque to use on this task (default: []).  Plugins like `QueueLock can be applied` */
+  plugins?: Array<
+    string | (new (args: ConstructorParameters<typeof Plugin>) => Plugin)
+  >;
+  /**Options for the node-resque plugins. */
+  pluginOptions?: { [key: string]: any };
+  /**Re-enqueuing a periodic task in the case of an exception.  (default: false) */
+  reEnqueuePeriodicTaskIfException?: boolean;
+
+  constructor() {
+    this.description = this.description ?? this.name;
+    this.frequency = this.frequency ?? 0;
+    this.queue = this.queue ?? "default";
+    this.middleware = this.middleware ?? [];
+    this.plugins = this.plugins ?? [];
+    this.pluginOptions = this.pluginOptions ?? {};
+    this.reEnqueuePeriodicTaskIfException =
+      this.reEnqueuePeriodicTaskIfException ?? true;
+  }
+
+  /**
+   * The main "do something" method for this task.  It can be `async`.  Anything returned from this method will be logged.
+   * If error is thrown in this method, it will be logged & caught.  Using middleware, you can decide to re-run the task on failure.
+   * `this` is a Task instance itself now.
+   *
+   * Inputs:
+   * * data: The data about this instance of the task, specifically params.
+   * * worker: Instance of a node-resque worker. You can inspect `worker.job` and set `worker.result` explicitly if your Task does not return a value.
+   */
+  abstract run(data: TaskInputs, worker: Worker): Promise<any>;
+
+  validate?() {
+    if (!this.name) {
+      throw new Error("name is required for this task");
+    }
+    if (!this.description) {
+      throw new Error(`description is required for the task \`${this.name}\``);
+    }
+    if (!this.queue) {
+      throw new Error(`queue is required for the task \`${this.name}\``);
+    }
+    if (this.frequency === null || this.frequency === undefined) {
+      throw new Error(`frequency is required for the task \`${this.name}\``);
+    }
+    if (!this.run || typeof this.run !== "function") {
+      throw new Error(`task \`${this.name}\` has no run method`);
+    }
+  }
+}
+
+export interface TaskInputs {
+  [key: string]: any;
+}

package/src/config/api.ts

@@ -0,0 +1,107 @@
+import * as path from "path";
+import * as fs from "fs";
+import { PackageJson } from "type-fest";
+import { ActionheroLogLevel } from "..";
+
+const namespace = "general";
+
+declare module ".." {
+  export interface ActionheroConfigInterface {
+    [namespace]: ReturnType<(typeof DEFAULT)[typeof namespace]>;
+  }
+}
+
+export const DEFAULT = {
+  [namespace]: () => {
+    const packageJSON: PackageJson = JSON.parse(
+      fs
+        .readFileSync(path.join(__dirname, "..", "..", "package.json"))
+        .toString(),
+    );
+
+    return {
+      apiVersion: packageJSON.version,
+      serverName: packageJSON.name,
+      // you can manually set the server id (not recommended)
+      id: undefined as string,
+      welcomeMessage: `Welcome to the ${packageJSON.name} api`,
+      // A unique token to your application that servers will use to authenticate to each other
+      serverToken: "change-me",
+      // the redis prefix for Actionhero cache objects
+      cachePrefix: "actionhero:cache:",
+      // the redis prefix for Actionhero cache/lock objects
+      lockPrefix: "actionhero:lock:",
+      // how long will a lock last before it expires (ms)?
+      lockDuration: 1000 * 10, // 10 seconds
+      // How many pending actions can a single connection be working on
+      simultaneousActions: 5,
+      // allow connections to be created without remoteIp and remotePort (they will be set to 0)
+      enforceConnectionProperties: true,
+      // disables the whitelisting of client params
+      disableParamScrubbing: false,
+      // enable action response to logger
+      enableResponseLogging: false,
+      // params you would like hidden from any logs. Can be an array of strings or a method that returns an array of strings.
+      filteredParams: [] as string[] | (() => string[]),
+      // responses you would like hidden from any logs. Can be an array of strings or a method that returns an array of strings.
+      filteredResponse: [] as string[] | (() => string[]),
+      // values that signify missing params
+      missingParamChecks: [null, "", undefined],
+      // The default filetype to server when a user requests a directory
+      directoryFileType: "index.html",
+      // What log-level should we use for file requests?
+      fileRequestLogLevel: "info" as ActionheroLogLevel,
+      // The default priority level given to middleware of all types (action, connection, say, and task)
+      defaultMiddlewarePriority: 100,
+      // Which channel to use on redis pub/sub for RPC communication
+      channel: "actionhero",
+      // How long to wait for an RPC call before considering it a failure
+      rpcTimeout: 5000,
+      // should CLI methods and help include internal Actionhero CLI methods?
+      cliIncludeInternal: true,
+      // configuration for your actionhero project structure
+      paths: {
+        action: [path.join(__dirname, "..", "actions")],
+        task: [path.join(__dirname, "..", "tasks")],
+        server: [path.join(__dirname, "..", "servers")],
+        cli: [path.join(__dirname, "..", "bin")],
+        initializer: [path.join(__dirname, "..", "initializers")],
+        public: [path.join(process.cwd(), "public")],
+        pid: [path.join(process.cwd(), "pids")],
+        log: [path.join(process.cwd(), "log")],
+        plugin: [path.join(process.cwd(), "node_modules")],
+        test: [path.join(process.cwd(), "__tests__")],
+        // for the src and dist paths, assume we are running in compiled mode from `dist`
+        src: path.join(process.cwd(), "src"),
+        dist: path.join(process.cwd(), "dist"),
+      },
+
+      // hash containing chat rooms you wish to be created at server boot
+      startingChatRooms: {
+        // format is {roomName: {authKey, authValue}}
+        // 'secureRoom': {authorized: true},
+      } as Record<string, Record<string, any>>,
+    };
+  },
+};
+
+export const test = {
+  [namespace]: () => {
+    return {
+      serverToken: `serverToken-${process.env.JEST_WORKER_ID || 0}`,
+      startingChatRooms: {
+        defaultRoom: {},
+        otherRoom: {},
+      },
+      rpcTimeout: 3000,
+    };
+  },
+};
+
+export const production = {
+  [namespace]: () => {
+    return {
+      fileRequestLogLevel: "debug",
+    };
+  },
+};

package/src/config/errors.ts

@@ -0,0 +1,162 @@
+import { ActionProcessor, Connection } from "..";
+
+const namespace = "errors";
+
+declare module ".." {
+  export interface ActionheroConfigInterface {
+    [namespace]: ReturnType<(typeof DEFAULT)[typeof namespace]>;
+  }
+}
+
+export const DEFAULT = {
+  [namespace]: () => {
+    return {
+      _toExpand: false,
+
+      // Should error types of "unknownAction" be included to the Exception handlers?
+      reportUnknownActions: false,
+
+      // ///////////////
+      // SERIALIZERS //
+      // ///////////////
+
+      serializers: {
+        servers: {
+          web: (error: NodeJS.ErrnoException) => {
+            if (error.message) {
+              return String(error.message);
+            } else {
+              return error;
+            }
+          },
+          websocket: (error: NodeJS.ErrnoException) => {
+            if (error.message) {
+              return String(error.message);
+            } else {
+              return error;
+            }
+          },
+          specHelper: (error: NodeJS.ErrnoException) => {
+            if (error.message) {
+              return "Error: " + String(error.message);
+            } else {
+              return error;
+            }
+          },
+        },
+        // See ActionProcessor#applyDefaultErrorLogLineFormat to see an example of how to customize
+        actionProcessor:
+          null as ActionProcessor<any>["applyDefaultErrorLogLineFormat"],
+      },
+
+      // ///////////
+      // ACTIONS //
+      // ///////////
+
+      // When a params for an action is invalid
+      invalidParams: (
+        data: ActionProcessor<any>,
+        validationErrors: Array<string | Error>,
+      ) => {
+        if (validationErrors.length >= 0) return validationErrors[0];
+        return "validation error";
+      },
+
+      // When a required param for an action is not provided
+      missingParams: (data: ActionProcessor<any>, missingParams: string[]) => {
+        return `${missingParams[0]} is a required parameter for this action`;
+      },
+
+      // user requested an unknown action
+      unknownAction: (data: ActionProcessor<any>) => {
+        return `unknown action or invalid apiVersion`;
+      },
+
+      // action not useable by this client/server type
+      unsupportedServerType: (data: ActionProcessor<any>) => {
+        return `this action does not support the ${data.connection.type} connection type`;
+      },
+
+      // action failed because server is mid-shutdown
+      serverShuttingDown: (data: ActionProcessor<any>) => {
+        return `the server is shutting down`;
+      },
+
+      // action failed because this client already has too many pending actions
+      // limit defined in api.config.general.simultaneousActions
+      tooManyPendingActions: (data: ActionProcessor<any>) => {
+        return `you have too many pending requests`;
+      },
+
+      // Decorate your response based on Error here.
+      // Any action that throws an Error will pass through this method before returning
+      //   an error to the client. Response can be edited here, status codes changed, etc.
+      async genericError(
+        data: ActionProcessor<any>,
+        error: NodeJS.ErrnoException,
+      ) {
+        return error;
+      },
+
+      // ///////////////
+      // FILE SERVER //
+      // ///////////////
+
+      // The body message to accompany 404 (file not found) errors regarding flat files
+      // You may want to load in the content of 404.html or similar
+      fileNotFound: (connection: Connection) => {
+        return `that file is not found`;
+      },
+
+      // user didn't request a file
+      fileNotProvided: (connection: Connection) => {
+        return `file is a required param to send a file`;
+      },
+
+      // something went wrong trying to read the file
+      fileReadError: (connection: Connection, error: NodeJS.ErrnoException) => {
+        return `error reading file: ${error?.message ?? error}`;
+      },
+
+      // ///////////////
+      // CONNECTIONS //
+      // ///////////////
+
+      verbNotFound: (connection: Connection, verb: string) => {
+        return `verb not found or not allowed (${verb})`;
+      },
+
+      verbNotAllowed: (connection: Connection, verb: string) => {
+        return `verb not found or not allowed (${verb})`;
+      },
+
+      connectionRoomAndMessage: (connection: Connection) => {
+        return `both room and message are required`;
+      },
+
+      connectionNotInRoom: (connection: Connection, room: string) => {
+        return `connection not in this room (${room})`;
+      },
+
+      connectionAlreadyInRoom: (connection: Connection, room: string) => {
+        return `connection already in this room (${room})`;
+      },
+
+      connectionRoomHasBeenDeleted: (room: string) => {
+        return "this room has been deleted";
+      },
+
+      connectionRoomNotExist: (room: string) => {
+        return "room does not exist";
+      },
+
+      connectionRoomExists: (room: string) => {
+        return "room exists";
+      },
+
+      connectionRoomRequired: () => {
+        return "a room is required";
+      },
+    };
+  },
+};