@nonstrict/recordkit 0.2.1 → 0.3.0-alpha.1

package/src/NonstrictRPC.test.ts

@@ -0,0 +1,98 @@
+import { NSRPC, NSRPCPerformClosureRequest } from './NonstrictRPC.js';
+import v8 from 'v8';
+
+// const finalizationRegistry = new FinalizationRegistry(async (destructor) => { console.log('==> ', destructor) })
+
+// finalizationRegistry.register({}, 'CHECK');
+// eval('%CollectGarbage(true)');
+
+describe('NonstrictRPC', () => {
+    it('needs tests', () => { });
+
+//     beforeAll(() => {
+//         v8.setFlagsFromString('--allow-natives-syntax');
+//     });
+
+//     describe('initialize', () => {
+//         it('sends init request w/parameters', (done) => {
+//             const rpc = new NSRPC((data) => {
+//                 const message = JSON.parse(data)
+//                 expect(message).toMatchSnapshot({ id: expect.any(String) });
+//                 done()
+//             });
+
+//             rpc.initialize({
+//                 target: 'TheTarget',
+//                 type: 'TheType',
+//                 params: { aParameter: 'TheValue' },
+//                 lifecycle: {}
+//             });
+//         });
+
+//         it('sends init request w/o parameters', (done) => {
+//             const rpc = new NSRPC((data) => {
+//                 const message = JSON.parse(data)
+//                 expect(message).toMatchSnapshot({ id: expect.any(String) });
+//                 done()
+//             });
+
+//             rpc.initialize({
+//                 target: 'TheTarget',
+//                 type: 'TheType',
+//                 lifecycle: {}
+//             });
+//         });
+
+//         it('sends release request', async () => {
+//             const rpc = new NSRPC((data) => {
+//                 const message = JSON.parse(data)
+//                 console.log(message)
+//                 // if (message.procedure === 'release') {
+//                 //     expect(message).toMatchSnapshot({ id: expect.any(String) });
+//                 //     done()
+//                 // }
+//             });
+
+//             async function scope() {
+//                 const foo = {}
+//                await rpc.initialize({
+//                     target: 'TheTarget',
+//                     type: 'TheType',
+//                     lifecycle: foo   
+//                 }); 
+//                 finalizationRegistry.register(foo, 'CHECK');
+//             }
+
+//             await scope();
+//             eval("%CollectGarbage(true)");
+//         });
+//     });
+
+//     describe('registerClosure', () => {
+//         it('should do something', (done) => {
+//             const rpc = new NSRPC((data) => {
+//                 expect(JSON.parse(data)).toStrictEqual({status:200,result:{test:"test"},nsrpc:1,id:"req_id"})
+//                 done()
+//             });
+
+//             const target = rpc.registerClosure({
+//                 handler: (params) => { params },
+//                 prefix: 'test',
+//                 lifecycle: {}
+//             });
+
+//             const rpcMessage: NSRPCPerformClosureRequest = {
+//                 nsrpc: 1,
+//                 id: 'req_id',
+//                 procedure: 'perform',
+//                 target,
+//                 params: { test: 'test' }
+//             }
+//             rpc.receive(JSON.stringify(rpcMessage));
+//         });x
+//     });
+
+//     function timeout(ms: number) {
+//         return new Promise<void>(resolve => setTimeout(resolve, ms));
+//       }
+});

package/src/NonstrictRPC.ts

@@ -0,0 +1,308 @@
+import { randomUUID } from "crypto";
+import { finalizationRegistry } from "./finalizationRegistry.js";
+
+type NSRPCMessage = NSRPCRequest | NSRPCResponse;
+
+/* Request types */
+
+type NSRPCRequest =
+  | NSRPCInitializationRequest
+  | NSRPCPerformStaticMethodRequest
+  | NSRPCPerformMethodRequest
+  | NSRPCPerformClosureRequest
+  | NSRPCReleaseRequest;
+
+interface NSRPCInitializationRequest {
+  nsrpc: number;
+  id: string;
+  procedure: "init";
+  target: string;
+  type: string;
+  params?: Record<string, unknown>;
+}
+
+interface NSRPCPerformStaticMethodRequest {
+  nsrpc: number;
+  id?: string;
+  procedure: "perform";
+  type: string;
+  action: string;
+  params?: Record<string, unknown>;
+}
+
+interface NSRPCPerformMethodRequest {
+  nsrpc: number;
+  id?: string;
+  procedure: "perform";
+  target: string;
+  action: string;
+  params?: Record<string, unknown>;
+}
+
+export interface NSRPCPerformClosureRequest {
+  nsrpc: number;
+  id?: string;
+  procedure: "perform";
+  target: string;
+  params?: Record<string, unknown>;
+}
+
+interface NSRPCReleaseRequest {
+  nsrpc: number;
+  id: string;
+  procedure: "release";
+  target: string;
+}
+
+type NSRPCRequestBody =
+  | NSRPCInitializationRequestBody
+  | NSRPCPerformStaticMethodRequestBody
+  | NSRPCPerformMethodRequestBody
+  | NSRPCPerformClosureRequestBody
+  | NSRPCReleaseRequestBody;
+type NSRPCInitializationRequestBody = Omit<
+  NSRPCInitializationRequest,
+  "nsrpc" | "id"
+>;
+type NSRPCPerformMethodRequestBody = Omit<
+  NSRPCPerformMethodRequest,
+  "nsrpc" | "id"
+>;
+type NSRPCPerformStaticMethodRequestBody = Omit<
+  NSRPCPerformStaticMethodRequest,
+  "nsrpc" | "id"
+>;
+type NSRPCPerformClosureRequestBody = Omit<
+  NSRPCPerformClosureRequest,
+  "nsrpc" | "id"
+>;
+type NSRPCReleaseRequestBody = Omit<NSRPCReleaseRequest, "nsrpc" | "id">;
+
+/* Response types */
+
+type NSRPCResponse = NSRPCSuccesfulResponse | NSRPCErrorResponse;
+
+interface NSRPCSuccesfulResponse {
+  nsrpc: number;
+  id: string;
+  status: 200;
+  result?: unknown;
+}
+
+interface NSRPCErrorResponse {
+  nsrpc: number;
+  id: string;
+  status: Exclude<number, 200>;
+  error: Record<string, unknown>;
+}
+
+type NSRPCResponseBody = NSRPCSuccesfulResponseBody | NSRPCErrorResponseBody;
+type NSRPCSuccesfulResponseBody = Omit<NSRPCSuccesfulResponse, "nsrpc" | "id">;
+type NSRPCErrorResponseBody = Omit<NSRPCErrorResponse, "nsrpc" | "id">;
+
+interface PromiseSource {
+  resolve: (
+    value: unknown
+  ) => void;
+  reject: (reason?: any) => void;
+}
+type ClosureTarget = (
+  params: Record<string, unknown>
+) => Record<string, unknown> | void;
+
+export class NSRPC {
+  private readonly send: (data: string) => void;
+
+  private responseHandlers: Map<string, PromiseSource> = new Map();
+  private closureTargets: Map<string, ClosureTarget> = new Map();
+
+  constructor(send: (data: string) => void) {
+    this.send = send;
+  }
+
+  receive(data: string) {
+    // TODO: For now we just assume the message is a valid NSRPC message, but we should:
+    // - Handle invalid JSON comming in
+    // - Check if the nsrpc property is set to a number in the range of 1..<2
+    // - Validate the message against the defined interfaces above
+    const message = JSON.parse(data) as NSRPCMessage;
+    if ("status" in message) {
+      // This is a response, dispatch it so it can be handled
+      const responseHandler = this.responseHandlers.get(message.id);
+      this.responseHandlers.delete(message.id);
+      if (responseHandler === undefined) {
+        // TODO: Got a response for a request we don't know about, log this
+        return;
+      }
+
+      if ("error" in message) {
+        responseHandler.reject(message.error);
+      } else {
+        responseHandler.resolve(message.result);
+      }
+    } else {
+      // This is a request
+      const responseBody = this.handleRequest(message);
+      if (responseBody !== undefined) {
+        this.sendResponse(message.id, responseBody);
+      }
+    }
+  }
+
+  /* Sending helpers */
+
+  private sendMessage(message: NSRPCMessage) {
+    this.send(JSON.stringify(message));
+  }
+
+  private sendResponse(id: string | undefined, response: NSRPCResponseBody) {
+    if (id === undefined) {
+      return;
+    }
+    this.sendMessage({ ...response, nsrpc: 1, id });
+  }
+
+  private async sendRequest(
+    request: NSRPCRequestBody
+  ): Promise<unknown> {
+    const id = "req_" + randomUUID();
+    const response = new Promise((resolve, reject) => {
+      this.responseHandlers.set(id, { resolve, reject });
+    });
+
+    this.sendMessage({ ...request, nsrpc: 1, id });
+
+    return response;
+  }
+
+  /* Request handling */
+
+  private handleRequest(request: NSRPCRequest): NSRPCResponseBody | undefined {
+    switch (request.procedure) {
+      case "init":
+        return {
+          status: 501,
+          error: {
+            debugDescription: "Init procedure not implemented.",
+            userMessage:
+              "Failed to communicate with external process. (Procedure not implemented)",
+          },
+        };
+      case "perform":
+        if ("action" in request) {
+          return {
+            status: 501,
+            error: {
+              debugDescription:
+                "Perform procedure for (static) methods not implemented.",
+              userMessage:
+                "Failed to communicate with external process. (Procedure not implemented)",
+            },
+          };
+        } else {
+          return this.handleClosureRequest(request);
+        }
+      case "release":
+        return {
+          status: 501,
+          error: {
+            debugDescription: "Release procedure not implemented.",
+            userMessage:
+              "Failed to communicate with external process. (Procedure not implemented)",
+          },
+        };
+    }
+  }
+
+  private handleClosureRequest(
+    request: NSRPCPerformClosureRequest
+  ): NSRPCResponseBody {
+    const handler = this.closureTargets.get(request.target);
+    if (handler === undefined) {
+      return {
+        status: 404,
+        error: {
+          debugDescription: `Perform target '${request.target}' not found.`,
+          userMessage:
+            "Failed to communicate with external process. (Target not found)",
+        },
+      };
+    }
+
+    try {
+      const rawresult = handler(request.params ?? {});
+      const result = rawresult === undefined ? undefined : rawresult;
+      return {
+        status: 200,
+        result,
+      };
+    } catch (error) {
+      return {
+        status: 202,
+        // TODO: Would be good to have an error type that we can throw that fills these fields more specifically. (But for now it doesn't matter since this is just communicated back the the CLI and not to the user.)
+        error: {
+          debugDescription: `${error}`,
+          userMessage: "Handler failed to perform request.",
+          underlyingError: error,
+        },
+      };
+    }
+  }
+
+  /* Perform remote procedures */
+
+  async initialize(args: {
+    target: string;
+    type: string;
+    params?: Record<string, unknown>;
+    lifecycle: Object;
+  }) {
+    const target = args.target
+    finalizationRegistry.register(args.lifecycle, async () => {
+      await this.release(target);
+    });
+
+    await this.sendRequest({
+      target: args.target,
+      type: args.type,
+      params: args.params,
+      procedure: "init",
+    });
+  }
+
+  async perform(body: { // TODO: Add support for static method calls.
+    type?: string;
+    target?: string;
+    action?: string;
+    params?: Record<string, unknown>;
+  }): Promise<unknown> {
+    return await this.sendRequest({
+      ...body,
+      procedure: "perform",
+    } as any);
+  }
+
+  private async release(target: string) {
+    await this.sendRequest({
+      procedure: "release",
+      target,
+    });
+  }
+
+  /* Register locally available targets/actions */
+
+  registerClosure(options: {
+    handler: ClosureTarget;
+    lifecycle: Object;
+    prefix: string;
+  }): string {
+    const target = `target_${options.prefix}_${randomUUID()}`;
+    this.closureTargets.set(target, options.handler);
+
+    finalizationRegistry.register(options.lifecycle, () => {
+      this.closureTargets.delete(target);
+    });
+
+    return target;
+  }
+}

package/src/RecordKit.ts

@@ -0,0 +1,99 @@
+import { IpcRecordKit } from "./IpcRecordKit.js";
+import { Recorder, RecorderSchema, AbortReason } from "./Recorder.js";
+import { existsSync } from "node:fs";
+
+type AuthorizationStatus =
+  | 'notDetermined' // The user has not yet made a choice.
+  | 'restricted' // The user cannot change the client's status, possibly due to active restrictions such as parental controls being in place.
+  | 'denied' // The user explicitly denied access to the hardware supporting a media type for the client.
+  | 'authorized' // Application is authorized to access the hardware.
+
+export interface Window {
+  id: number; // UInt32
+  title?: string;
+  frame: Bounds
+  level: number // Int
+  application_process_id?: number // Int32
+  application_name?: string
+}
+
+export interface Camera {
+  id: string;
+  name: string;
+  model_id: string;
+  manufacturer: string;
+  availability: 'available' | 'lidClosed' | 'unknownSuspended'
+}
+
+export interface Microphone {
+  id: string;
+  name: string;
+  model_id: string;
+  manufacturer: string;
+  availability: 'available' | 'lidClosed' | 'unknownSuspended'
+}
+
+export interface Bounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export class RecordKit {
+  private ipcRecordKit = new IpcRecordKit()
+
+  async initialize(args: { rpcBinaryPath: string, fallbackToNodeModules: boolean, logRpcMessages?: boolean }): Promise<void> {
+    let rpcBinaryPath = args.rpcBinaryPath
+    if (!args.fallbackToNodeModules) {
+      if (!existsSync(rpcBinaryPath)) {
+        console.log('Falling back to RPC binary from node_modules, no file at given RPC binary path.')
+        rpcBinaryPath = rpcBinaryPath.replace('node_modules/electron/dist/Electron.app/Contents/Resources', 'node_modules/@nonstrict/recordkit/bin')
+      }
+    }
+
+    return this.ipcRecordKit.initialize(rpcBinaryPath, args.logRpcMessages)
+  }
+
+  async getWindows(): Promise<Window[]> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'getWindows' }) as Window[]
+  }
+
+  async getCameras(): Promise<Camera[]> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'getCameras' }) as Camera[]
+  }
+
+  async getMicrophones(): Promise<Microphone[]> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'getMicrophones' }) as Microphone[]
+  }
+
+  async getCameraAuthorizationStatus(): Promise<AuthorizationStatus> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'getCameraAuthorizationStatus' }) as AuthorizationStatus
+  }
+
+  async getMicrophoneAuthorizationStatus(): Promise<AuthorizationStatus> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'getMicrophoneAuthorizationStatus' }) as AuthorizationStatus
+  }
+
+  async getScreenRecordingAccess(): Promise<boolean> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'getScreenRecordingAccess' }) as boolean
+  }
+
+  async requestCameraAccess(): Promise<boolean> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestCameraAccess' }) as boolean
+  }
+
+  async requestMicrophoneAccess(): Promise<boolean> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestMicrophoneAccess' }) as boolean
+  }
+
+  async requestScreenRecordingAccess(): Promise<void> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestScreenRecordingAccess' }) as void
+  }
+
+  async createRecorder(schema: RecorderSchema): Promise<Recorder> {
+    return Recorder.newInstance(this.ipcRecordKit.nsrpc, schema);
+  }
+}
+
+export let recordkit = new RecordKit();

package/src/Recorder.ts

@@ -0,0 +1,113 @@
+import { randomUUID } from "crypto";
+import { finalizationRegistry } from "./finalizationRegistry.js";
+import { NSRPC } from "./NonstrictRPC.js";
+import { EventEmitter } from "stream";
+import { Camera, Microphone, Window } from "./RecordKit.js";
+
+export interface RecorderSchema {
+  output_directory?: string
+  items: RecorderSchemaItem[]
+}
+
+export type RecorderSchemaItem =
+  | WebcamSchema
+  | WindowBasedCropSchema
+
+export interface WebcamSchema {
+  type: 'webcam'
+  filename?: string
+  camera: Camera | string
+  microphone: Microphone | string
+}
+
+export interface WindowBasedCropSchema {
+  type: 'windowBasedCrop'
+  filename?: string
+  window: Window | number // UInt32
+  shows_cursor?: boolean
+  mouse_events?: boolean
+}
+
+export type AbortReason =
+  | { reason: 'userStopped'; result: RecordingResult; }
+  | { reason: 'interrupted'; result: RecordingResult; error: RecordKitError; }
+  | { reason: 'failed'; error: RecordKitError; }
+
+export interface RecordingResult {
+  url: string
+  info: BundleInfo
+}
+
+export interface RecordKitError {
+  message?: string // Message describing the problem and possible recovery options, intended to be shown directly to the end-user.
+  error_group: string // Generic title, used for grouping related errors
+  debug_description: string // Detailed technical description of this error, used in debugging
+}
+
+export interface BundleInfo {
+  version: 1,
+  files: {
+    type: 'screen' | 'webcam' | 'mouse'
+    filename: string
+  }[]
+}
+
+export class Recorder extends EventEmitter {
+  private readonly rpc: NSRPC;
+  private readonly target: string;
+
+  static async newInstance(rpc: NSRPC, schema: RecorderSchema): Promise<Recorder> {
+    const target = 'Recorder_' + randomUUID();
+    const object = new Recorder(rpc, target);
+
+    schema.items.forEach(item => {
+      if (item.type == 'webcam') {
+        if (typeof item.camera != 'string') {
+          item.camera = item.camera.id
+        }
+        if (typeof item.microphone != 'string') {
+          item.microphone = item.microphone.id
+        }
+      }
+      if (item.type == 'windowBasedCrop') {
+        if (typeof item.window != 'number') {
+          item.window = item.window.id
+        }
+      }
+    })
+
+    const weakRefObject = new WeakRef(object);
+    const onAbortInstance = rpc.registerClosure({
+      handler: (params) => { weakRefObject.deref()?.emit('abort', params.reason as AbortReason) },
+      prefix: 'Recorder.onAbort',
+      lifecycle: object
+    });
+
+    await rpc.initialize({
+      target,
+      type: 'Recorder',
+      params: { schema, onAbortInstance },
+      lifecycle: object
+    });
+
+    return object
+  }
+
+  constructor(rpc: NSRPC, target: string) {
+    super();
+    this.rpc = rpc;
+    this.target = target;
+  }
+
+  async prepare(): Promise<void> {
+    await this.rpc.perform({ target: this.target, action: 'prepare' });
+  }
+
+  async start(): Promise<void> {
+    await this.rpc.perform({ target: this.target, action: 'start' });
+  }
+
+  async stop(): Promise<RecordingResult> {
+    return await this.rpc.perform({ target: this.target, action: 'stop' }) as RecordingResult;
+  }
+}

package/src/__snapshots__/NonstrictRPC.test.ts.snap

@@ -0,0 +1,24 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`NonstrictRPC initialize sends init request w/o parameters 1`] = `
+{
+  "id": Any<String>,
+  "nsrpc": 1,
+  "procedure": "init",
+  "target": "TheTarget",
+  "type": "TheType",
+}
+`;
+
+exports[`NonstrictRPC initialize sends init request w/parameters 1`] = `
+{
+  "id": Any<String>,
+  "nsrpc": 1,
+  "params": {
+    "aParameter": "TheValue",
+  },
+  "procedure": "init",
+  "target": "TheTarget",
+  "type": "TheType",
+}
+`;

package/src/finalizationRegistry.ts

@@ -0,0 +1,2 @@
+type Destructor = () => void
+export const finalizationRegistry = new FinalizationRegistry<Destructor>(async (destructor) => { await destructor() })

package/src/index.ts

@@ -0,0 +1,3 @@
+export type * from './RecordKit.js';
+export type * from './Recorder.js';
+export { recordkit } from './RecordKit.js';