@jeongsu816/matrix-bot-sdk 0.0.0-stage → 0.8.1

package/src/metrics/IMetricListener.ts

@@ -0,0 +1,57 @@
+import { IMetricContext } from "./contexts";
+
+/**
+ * A simple interface for listening for Metric updates. Should be plugged into
+ * something like Prometheus for recording.
+ *
+ * Metric names are defined in metric_names.ts - see documentation on the name
+ * for what the context object contains. All metrics have a context object,
+ * with applicable interface. See the IMetricContext interface for more
+ * information.
+ * @category Metrics
+ */
+export interface IMetricListener {
+    /**
+     * Called when the given metric should start being tracked. Will be
+     * paired with a matching onEndMetric() call.
+     * @param {string} metricName The metric being called.
+     * @param {IMetricContext} context Context for the metric. Never null.
+     */
+    onStartMetric(metricName: string, context: IMetricContext): void;
+
+    /**
+     * Called when the given metric should stop being tracked. Will have
+     * started with a matching onStartMetric() call.
+     * @param {string} metricName The metric being called.
+     * @param {any} context Context for the metric. Never null.
+     * @param {number} timeMs The measured time in milliseconds between
+     * the start and end.
+     */
+    onEndMetric(metricName: string, context: IMetricContext, timeMs: number): void;
+
+    /**
+     * Called when a linear metric (increasing/decreasing number) should
+     * be incremented.
+     * @param {string} metricName The metric being called.
+     * @param {IMetricContext} context Context for the metric. Never null.
+     * @param {number} amount The amount to add. Never negative or zero.
+     */
+    onIncrement(metricName: string, context: IMetricContext, amount: number);
+
+    /**
+     * Called when a linear metric (increasing/decreasing number) should
+     * be decremented.
+     * @param {string} metricName The metric being called.
+     * @param {IMetricContext} context Context for the metric. Never null.
+     * @param {number} amount The amount to subtract. Never negative or zero.
+     */
+    onDecrement(metricName: string, context: IMetricContext, amount: number);
+
+    /**
+     * Called when a linear metric (increasing/decreasing number) should
+     * be reset to zero.
+     * @param {string} metricName The metric being called.
+     * @param {IMetricContext} context Context for the metric. Never null.
+     */
+    onReset(metricName: string, context: IMetricContext);
+}

package/src/metrics/Metrics.ts

@@ -0,0 +1,134 @@
+import { IMetricListener } from "./IMetricListener";
+import { IMetricContext } from "./contexts";
+import { LogService } from "..";
+
+/**
+ * Tracks metrics.
+ * @category Metrics
+ */
+export class Metrics {
+    private listeners: IMetricListener[] = [];
+    private requestStartTimes: { [contextId: string]: number } = {};
+    private uid = 0;
+
+    /**
+     * Creates a new Metrics handler with optional parent handler. When
+     * a parent handler is defined, metrics will be automatically published
+     * upwards to the parent.
+     * @param {Metrics} parent Optional parent for upstream metrics.
+     */
+    constructor(parent: Metrics = null) {
+        if (parent !== null) {
+            this.registerListener({
+                onIncrement(metricName: string, context: IMetricContext, amount: number) {
+                    parent.listeners.forEach(h => h.onIncrement(metricName, context, amount));
+                },
+                onDecrement(metricName: string, context: IMetricContext, amount: number) {
+                    parent.listeners.forEach(h => h.onDecrement(metricName, context, amount));
+                },
+                onReset(metricName: string, context: IMetricContext) {
+                    parent.listeners.forEach(h => h.onReset(metricName, context));
+                },
+                onStartMetric(metricName: string, context: IMetricContext): void {
+                    parent.listeners.forEach(h => h.onStartMetric(metricName, context));
+                },
+                onEndMetric(metricName: string, context: IMetricContext, timeMs: number): void {
+                    parent.listeners.forEach(h => h.onEndMetric(metricName, context, timeMs));
+                },
+            });
+        }
+    }
+
+    /**
+     * Registers a metric listener.
+     * @param {IMetricListener} listener The listener.
+     */
+    public registerListener(listener: IMetricListener) {
+        this.listeners.push(listener);
+    }
+
+    /**
+     * De-registers a metric listener.
+     * @param {IMetricListener} listener The listener.
+     */
+    public unregisterListener(listener: IMetricListener) {
+        const idx = this.listeners.indexOf(listener);
+        if (idx !== -1) this.listeners.splice(idx, 1);
+    }
+
+    /**
+     * Starts a timer on a metric.
+     * @param {string} metricName The metric name.
+     * @param {IMetricContext} context The metric context. Expected to have a unique ID.
+     */
+    public start(metricName: string, context: IMetricContext) {
+        this.requestStartTimes[context.uniqueId] = new Date().getTime();
+        this.listeners.forEach(h => h.onStartMetric(metricName, context));
+    }
+
+    /**
+     * Ends a timer on a metric.
+     * @param {string} metricName The metric name.
+     * @param {IMetricContext} context The metric context. Expected to have a unique ID.
+     */
+    public end(metricName: string, context: IMetricContext) {
+        const timeMs = (new Date().getTime()) - this.requestStartTimes[context.uniqueId];
+        delete this.requestStartTimes[context.uniqueId];
+        this.listeners.forEach(h => h.onEndMetric(metricName, context, timeMs));
+
+        // Trim the context for logging
+        const trimmedContext = {};
+        for (const key of Object.keys(context)) {
+            if (key === 'client') {
+                const client = context[key];
+                trimmedContext[key] = `<MatrixClient ${client['userId'] || 'NoCachedUserID'}>`;
+            } else if (key === 'intent') {
+                const intent = context[key];
+                trimmedContext[key] = `<Intent ${intent['userId'] || 'NoImpersonatedUserID'}>`;
+            } else {
+                trimmedContext[key] = context[key];
+            }
+        }
+
+        LogService.trace("Metrics", metricName, trimmedContext, timeMs);
+    }
+
+    /**
+     * Increments a metric.
+     * @param {string} metricName The metric name.
+     * @param {IMetricContext} context The metric context. Expected to have a unique ID.
+     * @param {number} amount The amount.
+     */
+    public increment(metricName: string, context: IMetricContext, amount: number) {
+        this.listeners.forEach(h => h.onIncrement(metricName, context, amount));
+    }
+
+    /**
+     * Decrements a metric.
+     * @param {string} metricName The metric name.
+     * @param {IMetricContext} context The metric context. Expected to have a unique ID.
+     * @param {number} amount The amount.
+     */
+    public decrement(metricName: string, context: IMetricContext, amount: number) {
+        this.listeners.forEach(h => h.onDecrement(metricName, context, amount));
+    }
+
+    /**
+     * Resets a metric.
+     * @param {string} metricName The metric name.
+     * @param {IMetricContext} context The metric context. Expected to have a unique ID.
+     */
+    public reset(metricName: string, context: IMetricContext) {
+        this.listeners.forEach(h => h.onReset(metricName, context));
+    }
+
+    /**
+     * Assigns a unique ID to the context object, returning it back.
+     * @param {IMetricContext} context The context to modify.
+     * @returns {IMetricContext} The provided context.
+     */
+    public assignUniqueContextId(context: IMetricContext): IMetricContext {
+        context.uniqueId = `${new Date().getTime()}-${this.uid++}`;
+        return context;
+    }
+}

package/src/metrics/contexts.ts

@@ -0,0 +1,56 @@
+/**
+ * Default context for all metrics.
+ * @category Metrics
+ */
+import { MatrixClient } from "../MatrixClient";
+import { Intent } from "../appservice/Intent";
+import { IdentityClient } from "../identity/IdentityClient";
+
+export interface IMetricContext {
+    /**
+     * Unique identifier for the context object. Used to differentiate
+     * contexts over a start/end event.
+     */
+    uniqueId: string;
+}
+
+/**
+ * Metric context for function call metrics.
+ * @category Metrics
+ */
+export interface FunctionCallContext extends IMetricContext {
+    /**
+     * The function name being called
+     */
+    functionName: string;
+}
+
+/**
+ * Metric context for metrics from a MatrixClient
+ * @category Metrics
+ */
+export interface MatrixClientCallContext extends FunctionCallContext {
+    /**
+     * The client that raised the metric.
+     */
+    client: MatrixClient;
+}
+
+/**
+ * Metric context for metrics from an IdentityClient
+ * @category Metrics
+ */
+export interface IdentityClientCallContext extends FunctionCallContext {
+    client: IdentityClient;
+}
+
+/**
+ * Metric context for metrics from an Intent
+ * @category Metrics
+ */
+export interface IntentCallContext extends MatrixClientCallContext {
+    /**
+     * The intent that is raising the metric.
+     */
+    intent: Intent;
+}

package/src/metrics/decorators.ts

@@ -0,0 +1,94 @@
+import {
+    METRIC_IDENTITY_CLIENT_FAILED_FUNCTION_CALL,
+    METRIC_IDENTITY_CLIENT_FUNCTION_CALL,
+    METRIC_IDENTITY_CLIENT_SUCCESSFUL_FUNCTION_CALL,
+    METRIC_INTENT_FAILED_FUNCTION_CALL,
+    METRIC_INTENT_FUNCTION_CALL,
+    METRIC_INTENT_SUCCESSFUL_FUNCTION_CALL,
+    METRIC_MATRIX_CLIENT_FAILED_FUNCTION_CALL,
+    METRIC_MATRIX_CLIENT_FUNCTION_CALL,
+    METRIC_MATRIX_CLIENT_SUCCESSFUL_FUNCTION_CALL,
+} from "./names";
+import { IdentityClientCallContext, IntentCallContext, MatrixClientCallContext } from "./contexts";
+
+/**
+ * Times a MatrixClient function call for metrics.
+ * @category Metrics
+ */
+export function timedMatrixClientFunctionCall() {
+    return function(_target: unknown, functionName: string, descriptor: PropertyDescriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function(...args) {
+            const context = this.metrics.assignUniqueContextId(<MatrixClientCallContext>{
+                functionName,
+                client: this,
+            });
+            this.metrics.start(METRIC_MATRIX_CLIENT_FUNCTION_CALL, context);
+            try {
+                const result = await originalMethod.apply(this, args);
+                this.metrics.increment(METRIC_MATRIX_CLIENT_SUCCESSFUL_FUNCTION_CALL, context, 1);
+                return result;
+            } catch (e) {
+                this.metrics.increment(METRIC_MATRIX_CLIENT_FAILED_FUNCTION_CALL, context, 1);
+                throw e;
+            } finally {
+                this.metrics.end(METRIC_MATRIX_CLIENT_FUNCTION_CALL, context);
+            }
+        };
+    };
+}
+
+/**
+ * Times an IdentityClient function call for metrics.
+ * @category Metrics
+ */
+export function timedIdentityClientFunctionCall() {
+    return function(_target: unknown, functionName: string, descriptor: PropertyDescriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function(...args: any[]) {
+            const context = this.metrics.assignUniqueContextId(<IdentityClientCallContext>{
+                functionName,
+                client: this,
+            });
+            this.metrics.start(METRIC_IDENTITY_CLIENT_FUNCTION_CALL, context);
+            try {
+                const result = await originalMethod.apply(this, args);
+                this.metrics.increment(METRIC_IDENTITY_CLIENT_SUCCESSFUL_FUNCTION_CALL, context, 1);
+                return result;
+            } catch (e) {
+                this.metrics.increment(METRIC_IDENTITY_CLIENT_FAILED_FUNCTION_CALL, context, 1);
+                throw e;
+            } finally {
+                this.metrics.end(METRIC_IDENTITY_CLIENT_FUNCTION_CALL, context);
+            }
+        };
+    };
+}
+
+/**
+ * Times an Intent function call for metrics.
+ * @category Metrics
+ */
+export function timedIntentFunctionCall() {
+    return function(_target: unknown, functionName: string, descriptor: PropertyDescriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function(...args: any[]) {
+            const context = this.metrics.assignUniqueContextId(<IntentCallContext>{
+                functionName,
+                client: this.client,
+                intent: this,
+            });
+            this.metrics.start(METRIC_INTENT_FUNCTION_CALL, context);
+            try {
+                const result = await originalMethod.apply(this, args);
+                this.metrics.increment(METRIC_INTENT_SUCCESSFUL_FUNCTION_CALL, context, 1);
+                return result;
+            } catch (e) {
+                this.metrics.increment(METRIC_INTENT_FAILED_FUNCTION_CALL, context, 1);
+                throw e;
+            } finally {
+                this.metrics.end(METRIC_INTENT_FUNCTION_CALL, context);
+            }
+        };
+    };
+}

package/src/metrics/names.ts

@@ -0,0 +1,53 @@
+/**
+ * Time-series metric for how long a function call takes on MatrixClient. Uses a MatrixClientCallContext.
+ * @category Metrics
+ */
+export const METRIC_MATRIX_CLIENT_FUNCTION_CALL = "matrix_client_function_call";
+
+/**
+ * Counter metric for failed function calls on a MatrixClient. Uses a MatrixClientCallContext.
+ * @category Metrics
+ */
+export const METRIC_MATRIX_CLIENT_FAILED_FUNCTION_CALL = "matrix_client_failed_function_call";
+
+/**
+ * Counter metric for successful function calls on a MatrixClient. Uses a MatrixClientCallContext.
+ * @category Metrics
+ */
+export const METRIC_MATRIX_CLIENT_SUCCESSFUL_FUNCTION_CALL = "matrix_client_successful_function_call";
+
+/**
+ * Time-series metric for how long a function call takes on an IdentityClient. Uses an IdentityClientCallContext.
+ * @category Metrics
+ */
+export const METRIC_IDENTITY_CLIENT_FUNCTION_CALL = "identity_client_function_call";
+
+/**
+ * Counter metric for failed function calls on an IdentityClient. Uses an IdentityClientCallContext.
+ * @category Metrics
+ */
+export const METRIC_IDENTITY_CLIENT_FAILED_FUNCTION_CALL = "identity_client_failed_function_call";
+
+/**
+ * Counter metric for successful function calls on an IdentityClient. Uses an IdentityClientCallContext.
+ * @category Metrics
+ */
+export const METRIC_IDENTITY_CLIENT_SUCCESSFUL_FUNCTION_CALL = "identity_client_successful_function_call";
+
+/**
+ * Time-series metric for how long a function call takes on an Intent. Uses a IntentCallContext.
+ * @category Metrics
+ */
+export const METRIC_INTENT_FUNCTION_CALL = "intent_function_call";
+
+/**
+ * Counter metric for failed function calls on an Intent. Uses a IntentCallContext.
+ * @category Metrics
+ */
+export const METRIC_INTENT_FAILED_FUNCTION_CALL = "intent_failed_function_call";
+
+/**
+ * Counter metric for successful function calls on an Intent. Uses a IntentCallContext.
+ * @category Metrics
+ */
+export const METRIC_INTENT_SUCCESSFUL_FUNCTION_CALL = "intent_successful_function_call";

package/src/mixins/AutojoinRoomsMixin.ts

@@ -0,0 +1,24 @@
+import { MatrixClient } from "../MatrixClient";
+import { Appservice } from "../appservice/Appservice";
+
+/**
+ * Automatically accepts invites for rooms
+ * @category Mixins
+ */
+export class AutojoinRoomsMixin {
+    public static setupOnClient(client: MatrixClient): void {
+        client.on("room.invite", (roomId: string, inviteEvent: any) => {
+            return client.joinRoom(roomId);
+        });
+    }
+
+    public static setupOnAppservice(appservice: Appservice, conditional: (inviteEvent: any) => boolean = null): void {
+        appservice.on("room.invite", (roomId: string, inviteEvent: any) => {
+            const isFromBot = appservice.botUserId === inviteEvent["sender"];
+            if (!isFromBot && conditional && !conditional(inviteEvent)) return;
+
+            const intent = appservice.getIntentForUserId(inviteEvent["state_key"]);
+            return intent.joinRoom(roomId);
+        });
+    }
+}

package/src/mixins/AutojoinUpgradedRoomsMixin.ts

@@ -0,0 +1,37 @@
+import { MatrixClient } from "../MatrixClient";
+import { Appservice } from "../appservice/Appservice";
+
+/**
+ * Automatically tries to join upgraded rooms
+ * @category Mixins
+ */
+export class AutojoinUpgradedRoomsMixin {
+    public static setupOnClient(client: MatrixClient): void {
+        client.on("room.archived", (roomId: string, tombstoneEvent: any) => {
+            if (!tombstoneEvent['content']) return;
+            if (!tombstoneEvent['sender']) return;
+            if (!tombstoneEvent['content']['replacement_room']) return;
+
+            const serverName = tombstoneEvent['sender'].split(':').splice(1).join(':');
+            return client.joinRoom(tombstoneEvent['content']['replacement_room'], [serverName]);
+        });
+    }
+
+    public static setupOnAppservice(appservice: Appservice): void {
+        appservice.on("room.archived", async (roomId: string, tombstoneEvent: any) => {
+            if (!tombstoneEvent['content']) return;
+            if (!tombstoneEvent['sender']) return;
+            if (!tombstoneEvent['content']['replacement_room']) return;
+
+            const newRoomId = tombstoneEvent['content']['replacement_room'];
+            const serverName = tombstoneEvent['sender'].split(':').splice(1).join(':');
+            const botClient = appservice.botIntent.underlyingClient;
+
+            await botClient.joinRoom(newRoomId, [serverName]);
+            const userIds = await botClient.getJoinedRoomMembers(roomId);
+            const joinUserIds = userIds.filter(u => u !== appservice.botUserId && appservice.isNamespacedUser(u));
+
+            return await Promise.all(joinUserIds.map(u => appservice.getIntentForUserId(u).joinRoom(newRoomId)));
+        });
+    }
+}

package/src/models/Account.ts

@@ -0,0 +1,8 @@
+/**
+ * Response to a `/whoami` request.
+ * @category Models
+ */
+export interface IWhoAmI {
+    user_id: string;
+    device_id?: string;
+}

package/src/models/CreateRoom.ts

@@ -0,0 +1,144 @@
+import { PowerLevelsEventContent } from "./events/PowerLevelsEvent";
+import { CreateEventContent } from "./events/CreateEvent";
+
+/**
+ * "private_chat" sets:
+ * - join_rules to `invite`
+ * - history_visibility to `shared`
+ * - guest_access to `can_join`
+ *
+ * "trusted_private_chat" sets:
+ * - join_rules to `invite`
+ * - history_visibility to `shared`
+ * - guest_access to `can_join`
+ * - All invitees are given the same power level as the room creator.
+ *
+ * "public_chat" sets:
+ * - join_rules to `public`
+ * - history_visibility to `shared`
+ * - guest_access to `forbidden`
+ * @category Models
+ */
+export type RoomPreset = "private_chat" | "trusted_private_chat" | "public_chat";
+
+/**
+ * "public" visibility indicates that the room will be shown in the published room list.
+ *
+ * "private" visibility indicates that the room will not be included in published room list.
+ * @category Models
+ */
+export type RoomVisibility = "public" | "private";
+
+/**
+ * The options available when creating a room.
+ * @category Models
+ */
+export interface RoomCreateOptions {
+    /**
+     * Extra keys, such as m.federate, to be added to the content of the m.room.create event.
+     * The server will overwrite the following keys: `creator`, `room_version`.
+     * Future versions of the specification may allow the server to overwrite other keys.
+     */
+    creation_content?: Omit<CreateEventContent, "creator">;
+
+    /**
+     * A list of state events to set in the new room.
+     * This allows the user to override the default state events set in the new room.
+     * The expected format of the state events are an object with `type`, `state_key` and `content` keys set.
+     * Takes precedence over events set by `preset`, but gets overridden by `name` and `topic` keys.
+     */
+    initial_state?: {
+        /**
+         * The content of the event.
+         */
+        content: any;
+
+        /**
+         * The state_key of the state event. Defaults to an empty string.
+         */
+        state_key?: string;
+
+        /**
+         * The type of event to send.
+         */
+        type: string;
+    }[];
+
+    /**
+     * A list of user IDs to invite to the room. This will tell the server to invite everyone in the list to the newly created room.
+     */
+    invite?: string[];
+
+    invite_3pid?: {
+        /**
+         * The invitee’s third party identifier.
+         */
+        address: string;
+
+        /**
+         * An access token previously registered with the identity server.
+         * Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.
+         */
+        id_access_token: string;
+
+        /**
+         * The hostname+port of the identity server which should be used for third party identifier lookups.
+         */
+        id_server: string;
+
+        /**
+         * The kind of address being passed in the address field, for example `email`.
+         */
+        medium: string;
+    }[];
+
+    /**
+     * This flag makes the server set the `is_direct` flag on the `m.room.member` events sent to the users in `invite` and `invite_3pid`.
+     */
+    is_direct?: boolean;
+
+    /**
+     * If this is included, an `m.room.name` event will be sent into the room to indicate the name of the room.
+     */
+    name?: string;
+
+    /**
+     * The power level content to override in the default power level event.
+     * This object is applied on top of the generated `m.room.power_levels` event content prior to it being sent to the room.
+     * Defaults to overriding nothing.
+     */
+    power_level_content_override?: PowerLevelsEventContent;
+
+    /**
+     * Convenience parameter for setting various default state events based on a preset.
+     *
+     * If unspecified, the server should use the `visibility` to determine which preset to use.
+     * A visbility of `public` equates to a preset of `public_chat` and `private` visibility equates to a preset of `private_chat`.
+     */
+    preset?: RoomPreset;
+
+    /**
+     * The desired room alias local part.
+     * If this is included, a room alias will be created and mapped to the newly created room.
+     * The alias will belong on the same homeserver which created the room.
+     */
+    room_alias_name?: string;
+
+    /**
+     * The room version to set for the room.
+     * If not provided, the homeserver is to use its configured default.
+     * If provided, the homeserver will return a `400` error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not support the room version.
+     */
+    room_version?: string;
+
+    /**
+     * If this is included, an `m.room.topic` event will be sent into the room to indicate the topic for the room.
+     */
+    topic?: string;
+
+    /**
+     * Sets the visibility of the room
+     * Rooms default to private visibility if this key is not included.
+     */
+    visibility?: RoomVisibility;
+}