feat: adding types

src/index.test.ts

@@ -1,9 +1,9 @@
-import { Wiregasm } from ".";
+import { Wiregasm, WiregasmLib, WiregasmLibOverrides } from ".";
 import loadWiregasm from "../built/bin/wiregasm.js";
 import * as fs from "fs/promises";
 
 // overrides need to be copied over to every instance
-const buildTestOverrides = () => {
+const buildTestOverrides = (): WiregasmLibOverrides => {
   return {
     locateFile: (path, prefix) => {
       if (path.endsWith(".data")) return "built/share/wiregasm/" + path;
@@ -20,7 +20,7 @@ const buildTestOverrides = () => {
 };
 
 describe("Wiregasm Library", () => {
-  let lib;
+  let lib: WiregasmLib;
   beforeAll(async () => {
     lib = await loadWiregasm(buildTestOverrides());
     lib.init();

src/index.ts

@@ -1,30 +1,65 @@
+import {
+  CheckFilterResponse,
+  DissectSession,
+  Frame,
+  FramesResponse,
+  LoadResponse,
+  WiregasmLib,
+  WiregasmLibOverrides,
+  WiregasmLoader,
+} from "./types";
+import { vectorToArray } from "./utils";
+
+/**
+ * Wraps the WiregasmLib lib functionality and manages a single DissectSession
+ */
 export class Wiregasm {
-  lib: any;
+  lib: WiregasmLib;
   initialized: boolean;
-  session: any;
+  session: DissectSession | null;
   uploadDir: string;
 
   constructor() {
     this.initialized = false;
     this.session = null;
   }
 
-  async init(loader: any, overrides: object = {}) {
+  /**
+   * Initialize the wrapper and the Wiregasm module
+   *
+   * @param loader Loader function for the Emscripten module
+   * @param overrides Overrides
+   */
+  async init(loader: WiregasmLoader, overrides: WiregasmLibOverrides = {}) {
     if (this.initialized) {
       return;
     }
-    this.initialized = true;
 
     this.lib = await loader(overrides);
     this.uploadDir = this.lib.getUploadDirectory();
     this.lib.init();
+    this.initialized = true;
   }
 
-  test_filter(filter: string): any {
+  /**
+   * Check the validity of a filter expression.
+   *
+   * @param filter A display filter expression
+   */
+  test_filter(filter: string): CheckFilterResponse {
     return this.lib.checkFilter(filter);
   }
 
-  load(name: string, data: string | ArrayBufferView, opts: object = {}): any {
+  /**
+   * Load a packet trace file for analysis.
+   *
+   * @returns Response containing the status and summary
+   */
+  load(
+    name: string,
+    data: string | ArrayBufferView,
+    opts: object = {}
+  ): LoadResponse {
     if (this.session != null) {
       this.session.delete();
     }
@@ -37,11 +72,23 @@ export class Wiregasm {
     return this.session.load();
   }
 
-  frames(filter: string, skip = 0, limit = 0): any {
+  /**
+   * Get Packet List information for a range of packets.
+   *
+   * @param filter Output those frames that pass this filter expression
+   * @param skip Skip N frames
+   * @param limit Limit the output to N frames
+   */
+  frames(filter: string, skip = 0, limit = 0): FramesResponse {
     return this.session.getFrames(filter, skip, limit);
   }
 
-  frame(num: number): any {
+  /**
+   * Get full information about a frame including the protocol tree.
+   *
+   * @param number Frame number
+   */
+  frame(num: number): Frame {
     return this.session.getFrame(num);
   }
 
@@ -57,10 +104,16 @@ export class Wiregasm {
     }
   }
 
+  /**
+   * Returns the column headers
+   */
   columns(): string[] {
     const vec = this.lib.getColumns();
 
     // convert it from a vector to array
-    return new Array(vec.size()).fill(0).map((_, id) => vec.get(id));
+    return vectorToArray(vec);
   }
 }
+
+export * from "./types";
+export * from "./utils";

src/types.ts

@@ -0,0 +1,204 @@
+export interface EmscriptenFileSystem {
+  writeFile(
+    path: string,
+    data: string | ArrayBufferView,
+    opts?: { flags?: string | undefined }
+  ): void;
+  readdir(path: string): string[];
+}
+
+export interface EmscriptenHeap {
+  buffer: ArrayBufferLike;
+}
+
+export interface EmscriptenModule {
+  FS: EmscriptenFileSystem;
+  HEAPU8: EmscriptenHeap;
+  _malloc(size: number): number;
+}
+
+export interface Vector<T> {
+  size(): number;
+  get(index: number): T;
+}
+
+export interface DataSource {
+  name: string;
+  data: string;
+}
+
+export interface ProtoTree {
+  label: string;
+  filter: string;
+  start: number;
+  length: number;
+  data_source_idx: number;
+  tree: Vector<ProtoTree>;
+}
+
+export interface Frame {
+  number: number;
+  comments: Vector<string>;
+  data_sources: Vector<DataSource>;
+  tree: Vector<ProtoTree>;
+}
+
+export interface FramesResponse {
+  frames: Vector<FrameMeta>;
+  matched: number;
+}
+
+export interface FrameMeta {
+  number: number;
+  comments: boolean;
+  ignored: boolean;
+  marked: boolean;
+  bg: number;
+  fg: number;
+  columns: Vector<string>;
+}
+
+export interface LoadSummary {
+  filename: string;
+  file_type: string;
+  file_length: number;
+  file_encap_type: string;
+  packet_count: number;
+  start_time: number;
+  stop_time: number;
+  elapsed_time: number;
+}
+
+export interface LoadResponse {
+  code: number;
+  error: string;
+  summary: LoadSummary;
+}
+
+export interface DissectSession {
+  /**
+   * Free up any memory used by the session
+   */
+  delete(): void;
+
+  /**
+   * Load a packet trace file for analysis.
+   *
+   * @returns Response containing the status and summary
+   */
+  load(): LoadResponse;
+
+  /**
+   * Get Packet List information for a range of packets.
+   *
+   * @param filter Output those frames that pass this filter expression
+   * @param skip Skip N frames
+   * @param limit Limit the output to N frames
+   */
+  getFrames(filter: string, skip: number, limit: number): FramesResponse;
+
+  /**
+   * Get full information about a frame including the protocol tree.
+   *
+   * @param number Frame number
+   */
+  getFrame(number: number): Frame;
+}
+
+export interface DissectSessionConstructable {
+  new (path: string): DissectSession;
+}
+
+export interface CheckFilterResponse {
+  ok: boolean;
+  error: string;
+}
+
+export interface WiregasmLibOverrides {
+  /**
+   * If set, this method will be called when the runtime needs to load a file,
+   * such as a .wasm WebAssembly file, .mem memory init file, or a file generated
+   * by the file packager. The function receives the relative path to the file as
+   * configured in build process and a prefix (path to the main JavaScript file’s
+   * directory), and should return the actual URL.
+   *
+   * This lets you host file packages or the .mem file etc. on a different location
+   * than the directory of the JavaScript file (which is the default expectation),
+   * for example if you want to host them on a CDN.
+   *
+   * @param path Path of the requested file.
+   * @param prefix Prefix of the requested path. May be empty.
+   *
+   * @returns Path to the requested file.
+   */
+  locateFile?(path: string, prefix: string): string;
+
+  /**
+   * Called when something is printed to standard error (stderr)
+   *
+   * @param error Error content
+   */
+  printErr?(error: string): void;
+
+  /**
+   * Called when something is printed to standard output (stdout)
+   *
+   * @param message Message content
+   */
+  print?(message: string): void;
+
+  /**
+   * Called from within the Wiregasm Library to notify
+   * about any status updates.
+   *
+   * @param type Type of the status
+   * @param message Message content
+   */
+  handleStatus?(type: number, message: string): void;
+}
+
+export interface WiregasmLib extends EmscriptenModule {
+  DissectSession: DissectSessionConstructable;
+
+  /**
+   * Returns the directory where files are uploaded
+   *
+   * @returns Path of the directory
+   */
+  getUploadDirectory(): string;
+
+  /**
+   * Initialize the library, load preferences and register dissectors
+   */
+  init(): boolean;
+
+  /**
+   * Clean up any memory associated with the lib
+   */
+  destroy(): void;
+
+  /**
+   * Check the validity of a filter expression.
+   *
+   * @param filter A display filter expression
+   */
+  checkFilter(filter: string): CheckFilterResponse;
+
+  /**
+   * Returns the column headers
+   */
+  getColumns(): Vector<string>;
+
+  /**
+   * Creates a new file in the upload directory with the supplied data
+   *
+   * @param file_name Name of the file
+   * @param data_ptr Pointer to the data
+   * @param length Length of the data
+   */
+  upload(file_name: string, data_ptr: number, length: number): string;
+}
+
+export type WiregasmLoader = (
+  overrides: WiregasmLibOverrides
+) => Promise<WiregasmLib>;

src/utils.ts

@@ -0,0 +1,11 @@
+import { Vector } from "./types";
+
+/**
+ * Converts a Vector to a JS array
+ *
+ * @param vec Vector
+ * @returns JS array of the Vector contents
+ */
+export function vectorToArray<T>(vec: Vector<T>): T[] {
+  return new Array(vec.size()).fill(0).map((_, id) => vec.get(id));
+}