@ecobridge.xyz/devicemanager 3.1.0 → 3.2.0

package/ts/protocols/protocol.brother.ts

@@ -0,0 +1,648 @@
+import * as plugins from '../plugins.js';
+import type {
+  IScanArea,
+  IScanCapabilities,
+  IScanResult,
+  TColorMode,
+  TScanFormat,
+  TScanSource,
+} from '../interfaces/index.js';
+
+const BROTHER_SCAN_PORT = 54921;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_SCAN_TIMEOUT_MS = 10 * 60_000;
+const DEFAULT_BUSY_RETRY_INTERVAL_MS = 1_000;
+const DEFAULT_BUSY_TIMEOUT_MS = 30_000;
+const MAX_PAGES = 500;
+const MAX_PAGE_BYTES = 256 * 1024 * 1024;
+const TERMINATOR = 0x80;
+
+export type TBrotherScanErrorCode =
+  | 'busy'
+  | 'cancelled'
+  | 'cover-open'
+  | 'device-stuck'
+  | 'document-jam'
+  | 'invalid-response'
+  | 'no-document'
+  | 'service-error'
+  | 'settings-rejected'
+  | 'timeout'
+  | 'unsupported';
+
+export class BrotherScanError extends Error {
+  constructor(
+    message: string,
+    public readonly code: TBrotherScanErrorCode,
+    public readonly statusCode?: number
+  ) {
+    super(message);
+    this.name = 'BrotherScanError';
+  }
+}
+
+export interface IBrotherScanProtocolOptions {
+  timeout?: number;
+  scanTimeout?: number;
+  busyRetryInterval?: number;
+  busyTimeout?: number;
+}
+
+export interface IBrotherScanLease {
+  resolutionX: number;
+  resolutionY: number;
+  adfStatus: number;
+  planeWidth: number;
+  width: number;
+  planeHeight: number;
+  height: number;
+}
+
+export interface IBrotherScanOptions {
+  resolution: number;
+  format: TScanFormat;
+  colorMode: TColorMode;
+  source: TScanSource;
+  area: IScanArea;
+  quality?: number;
+}
+
+type TFrameMode = 'simple' | 'wrapped';
+
+class SocketBuffer {
+  private buffer = Buffer.alloc(0);
+  private error: Error | null = null;
+  private ended = false;
+
+  constructor(private readonly socket: plugins.net.Socket) {
+    socket.on('data', (data: Buffer) => {
+      this.buffer = Buffer.concat([this.buffer, data]);
+    });
+    socket.on('error', (error) => {
+      this.error = error;
+    });
+    socket.on('end', () => {
+      this.ended = true;
+    });
+    socket.on('close', () => {
+      this.ended = true;
+    });
+  }
+
+  public discard(): void {
+    this.buffer = Buffer.alloc(0);
+  }
+
+  public async readExactly(length: number, timeout: number): Promise<Buffer> {
+    await this.waitForLength(length, timeout);
+    const result = this.buffer.subarray(0, length);
+    this.buffer = this.buffer.subarray(length);
+    return result;
+  }
+
+  public async peekExactly(length: number, timeout: number): Promise<Buffer> {
+    await this.waitForLength(length, timeout);
+    return this.buffer.subarray(0, length);
+  }
+
+  public async readUntil(delimiter: Buffer, timeout: number, maxLength: number): Promise<Buffer> {
+    const deadline = Date.now() + timeout;
+    while (true) {
+      const index = this.buffer.indexOf(delimiter);
+      if (index >= 0) {
+        const end = index + delimiter.length;
+        const result = this.buffer.subarray(0, end);
+        this.buffer = this.buffer.subarray(end);
+        return result;
+      }
+      if (this.buffer.length > maxLength) {
+        throw new BrotherScanError('Brother scanner response exceeded the expected length', 'invalid-response');
+      }
+      await this.waitForData(deadline);
+    }
+  }
+
+  public async readMatch(pattern: RegExp, timeout: number, maxLength: number): Promise<RegExpMatchArray> {
+    const deadline = Date.now() + timeout;
+    while (true) {
+      const match = this.buffer.toString('latin1').match(pattern);
+      if (match) return match;
+      if (this.buffer.length > maxLength) {
+        throw new BrotherScanError('Brother scanner lease response was malformed', 'invalid-response');
+      }
+      await this.waitForData(deadline);
+    }
+  }
+
+  private async waitForLength(length: number, timeout: number): Promise<void> {
+    const deadline = Date.now() + timeout;
+    while (this.buffer.length < length) {
+      await this.waitForData(deadline);
+    }
+  }
+
+  private async waitForData(deadline: number): Promise<void> {
+    if (this.error) throw this.error;
+    if (this.ended) {
+      throw new BrotherScanError('Brother scanner closed the connection', 'invalid-response');
+    }
+
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      throw new BrotherScanError('Timed out waiting for the Brother scanner', 'timeout');
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timer);
+        this.socket.off('data', onData);
+        this.socket.off('error', onError);
+        this.socket.off('end', onEnd);
+        this.socket.off('close', onEnd);
+      };
+      const onData = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = (error: Error) => {
+        cleanup();
+        reject(error);
+      };
+      const onEnd = () => {
+        cleanup();
+        reject(new BrotherScanError('Brother scanner closed the connection', 'invalid-response'));
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new BrotherScanError('Timed out waiting for the Brother scanner', 'timeout'));
+      }, remaining);
+
+      this.socket.once('data', onData);
+      this.socket.once('error', onError);
+      this.socket.once('end', onEnd);
+      this.socket.once('close', onEnd);
+    });
+  }
+}
+
+/**
+ * Brother's native network scan protocol on TCP 54921.
+ *
+ * Brother devices expose richer scan control here than they do through some
+ * eSCL implementations. The protocol returns one JPEG stream per sheet/side.
+ */
+export class BrotherScanProtocol {
+  private socket: plugins.net.Socket | null = null;
+  private reader: SocketBuffer | null = null;
+  private scanning = false;
+  private cancelled = false;
+  private readonly timeout: number;
+  private readonly scanTimeout: number;
+  private readonly busyRetryInterval: number;
+  private readonly busyTimeout: number;
+
+  constructor(
+    private readonly address: string,
+    private readonly port: number = BROTHER_SCAN_PORT,
+    options: IBrotherScanProtocolOptions = {}
+  ) {
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.scanTimeout = options.scanTimeout ?? DEFAULT_SCAN_TIMEOUT_MS;
+    this.busyRetryInterval = options.busyRetryInterval ?? DEFAULT_BUSY_RETRY_INTERVAL_MS;
+    this.busyTimeout = options.busyTimeout ?? DEFAULT_BUSY_TIMEOUT_MS;
+  }
+
+  public async connect(): Promise<void> {
+    if (this.socket && !this.socket.destroyed) return;
+
+    const busyDeadline = Date.now() + this.busyTimeout;
+    while (true) {
+      try {
+        await this.connectOnce();
+        return;
+      } catch (error) {
+        await this.disconnect();
+        if (
+          !(error instanceof BrotherScanError) ||
+          error.code !== 'busy' ||
+          Date.now() >= busyDeadline
+        ) {
+          throw error;
+        }
+        await delay(Math.min(this.busyRetryInterval, Math.max(0, busyDeadline - Date.now())));
+      }
+    }
+  }
+
+  private async connectOnce(): Promise<void> {
+    const socket = new plugins.net.Socket();
+    socket.setNoDelay(true);
+    this.socket = socket;
+    this.reader = new SocketBuffer(socket);
+
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        socket.destroy();
+        reject(new BrotherScanError('Timed out connecting to the Brother scanner', 'timeout'));
+      }, this.timeout);
+      const cleanup = () => {
+        clearTimeout(timer);
+        socket.off('connect', onConnect);
+        socket.off('error', onError);
+      };
+      const onConnect = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = (error: Error) => {
+        cleanup();
+        reject(error);
+      };
+      socket.once('connect', onConnect);
+      socket.once('error', onError);
+      socket.connect(this.port, this.address);
+    });
+
+    const banner = (await this.requireReader().readUntil(Buffer.from('\r\n'), this.timeout, 128))
+      .toString('ascii')
+      .trim();
+    if (banner.startsWith('+OK 200')) return;
+    if (banner.startsWith('-NG 401')) {
+      throw new BrotherScanError('Brother scanner is busy', 'busy');
+    }
+    throw new BrotherScanError(`Unexpected Brother scanner banner: ${banner}`, 'invalid-response');
+  }
+
+  public async disconnect(): Promise<void> {
+    const socket = this.socket;
+    this.socket = null;
+    this.reader = null;
+    this.scanning = false;
+    if (!socket || socket.destroyed) return;
+
+    await new Promise<void>((resolve) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        socket.off('close', finish);
+        socket.off('error', finish);
+        if (!socket.destroyed) socket.destroy();
+        resolve();
+      };
+      const timer = setTimeout(finish, 250);
+      socket.once('close', finish);
+      socket.once('error', finish);
+      socket.end();
+    });
+  }
+
+  public getCapabilities(): IScanCapabilities {
+    return {
+      resolutions: [100, 150, 200, 300, 600],
+      formats: ['jpeg'],
+      colorModes: ['color'],
+      sources: ['flatbed', 'adf', 'adf-duplex'],
+      maxWidth: 215.9,
+      maxHeight: 355.6,
+      minWidth: 10,
+      minHeight: 10,
+    };
+  }
+
+  public async scan(options: IBrotherScanOptions): Promise<IScanResult> {
+    if (!this.socket || !this.reader) {
+      throw new Error('Brother scanner is not connected');
+    }
+    if (this.scanning) {
+      throw new BrotherScanError('A Brother scan is already in progress', 'busy');
+    }
+    this.validateOptions(options);
+
+    this.scanning = true;
+    this.cancelled = false;
+    try {
+      await this.selectSource(options.source);
+      const lease = await this.requestLease(options.resolution);
+      this.assertLease(lease, options);
+
+      const area = this.resolveScanArea(options.area, lease);
+      await this.writeCommand([
+        '\x1bX',
+        `R=${lease.resolutionX},${lease.resolutionY}`,
+        'M=CGRAY',
+        'C=JPEG',
+        'J=MID',
+        'B=50',
+        'N=50',
+        `A=${area.x},${area.y},${area.x + area.width},${area.y + area.height}`,
+        options.source === 'adf-duplex' ? 'D=DUP' : 'D=SIN',
+      ]);
+
+      const pages = await this.readPages();
+      if (pages.length === 0) {
+        throw new BrotherScanError('Brother scanner returned no document data', 'no-document');
+      }
+
+      const firstMetadata = readJpegMetadata(pages[0]);
+      return {
+        data: pages[0],
+        format: 'jpeg',
+        width: firstMetadata.width ?? area.width,
+        height: firstMetadata.height ?? area.height,
+        resolution: firstMetadata.resolution ?? lease.resolutionX,
+        colorMode: 'color',
+        mimeType: 'image/jpeg',
+        pageCount: pages.length,
+        pages: pages.map((data) => {
+          const metadata = readJpegMetadata(data);
+          return {
+            data,
+            width: metadata.width ?? area.width,
+            height: metadata.height ?? area.height,
+            mimeType: 'image/jpeg',
+          };
+        }),
+        isComplete: true,
+        settingsWarnings: [],
+      };
+    } catch (error) {
+      if (this.cancelled) {
+        throw new BrotherScanError('Brother scan was cancelled', 'cancelled');
+      }
+      try {
+        await this.write(Buffer.from([0x1b, 0x52]));
+      } catch {
+        // Preserve the scan error if the connection is already gone.
+      }
+      throw error;
+    } finally {
+      this.scanning = false;
+    }
+  }
+
+  public async cancel(): Promise<void> {
+    if (!this.socket || !this.scanning) return;
+    this.cancelled = true;
+    await this.write(Buffer.from([0x1b, 0x52]));
+  }
+
+  private validateOptions(options: IBrotherScanOptions): void {
+    if (options.format !== 'jpeg') {
+      throw new BrotherScanError(
+        `Brother native scanning returns JPEG pages, not ${options.format}`,
+        'unsupported'
+      );
+    }
+    if (options.colorMode !== 'color') {
+      throw new BrotherScanError(
+        `Brother native ${options.colorMode} decoding is not implemented`,
+        'unsupported'
+      );
+    }
+  }
+
+  private async selectSource(source: TScanSource): Promise<void> {
+    const brotherSource = source === 'flatbed' ? 'FB' : 'AUTO';
+    await this.writeCommand(['\x1bS', brotherSource]);
+    const response = await this.requireReader().readExactly(1, this.timeout);
+    if (response[0] !== TERMINATOR) {
+      throw this.statusError(response[0], 'Brother scanner rejected the requested source');
+    }
+  }
+
+  private async requestLease(resolution: number): Promise<IBrotherScanLease> {
+    await this.writeCommand(['\x1bI', `R=${resolution},${resolution}`, 'M=CGRAY']);
+    const match = await this.requireReader().readMatch(
+      /(\d+),(\d+),(\d+),(\d+),(\d+),(\d+),(\d+)/,
+      this.timeout,
+      256
+    );
+    this.requireReader().discard();
+    const values = match.slice(1).map((value) => Number.parseInt(value, 10));
+    return {
+      resolutionX: values[0],
+      resolutionY: values[1],
+      adfStatus: values[2],
+      planeWidth: values[3],
+      width: values[4],
+      planeHeight: values[5],
+      height: values[6],
+    };
+  }
+
+  private assertLease(lease: IBrotherScanLease, options: IBrotherScanOptions): void {
+    if (lease.resolutionX !== options.resolution || lease.resolutionY !== options.resolution) {
+      throw new BrotherScanError(
+        `Brother scanner rejected ${options.resolution} dpi and offered ${lease.resolutionX}x${lease.resolutionY} dpi`,
+        'settings-rejected'
+      );
+    }
+    if (lease.width <= 0 || lease.height < 0) {
+      throw new BrotherScanError('Brother scanner returned an invalid scan area', 'invalid-response');
+    }
+  }
+
+  private resolveScanArea(area: IScanArea, lease: IBrotherScanLease): IScanArea {
+    const mmToPixels = (millimetres: number, dpi: number) => Math.round((millimetres * dpi) / 25.4);
+    const x = Math.max(0, mmToPixels(area.x, lease.resolutionX));
+    const y = Math.max(0, mmToPixels(area.y, lease.resolutionY));
+    const requestedWidth = mmToPixels(area.width, lease.resolutionX);
+    const requestedHeight = mmToPixels(area.height, lease.resolutionY);
+    const width = Math.max(1, Math.min(requestedWidth, lease.width - x));
+    // Brother ADF leases report zero height because page length is determined
+    // while feeding. Platen leases provide a fixed pixel height.
+    const height = lease.height === 0
+      ? Math.max(1, requestedHeight)
+      : Math.max(1, Math.min(requestedHeight, lease.height - y));
+    if (x >= lease.width || (lease.height > 0 && y >= lease.height)) {
+      throw new BrotherScanError('Requested scan area is outside the scanner bed', 'settings-rejected');
+    }
+    return { x, y, width, height };
+  }
+
+  private async readPages(): Promise<Buffer[]> {
+    const pages: Buffer[] = [];
+    let chunks: Buffer[] = [];
+    let pageBytes = 0;
+    const wrappedChunks = new Map<number, Buffer[]>();
+    const wrappedPageBytes = new Map<number, number>();
+    const wrappedPages = new Map<number, Buffer>();
+    let frameMode: TFrameMode | undefined;
+
+    while (pages.length + wrappedPages.size < MAX_PAGES) {
+      const header = (await this.requireReader().readExactly(1, this.scanTimeout))[0];
+
+      if (header < 0x80) {
+        const lengthBytes = await this.requireReader().readExactly(2, this.scanTimeout);
+        const firstLength = lengthBytes.readUInt16LE(0);
+        if (!frameMode) {
+          const startsWithJpeg = firstLength >= 2 &&
+            (await this.requireReader().peekExactly(2, this.scanTimeout)).equals(Buffer.from([0xff, 0xd8]));
+          frameMode = firstLength <= 64 && !startsWithJpeg ? 'wrapped' : 'simple';
+        }
+
+        if (frameMode === 'wrapped') {
+          const metadata = await this.requireReader().readExactly(firstLength, this.scanTimeout);
+          const dataLengthBytes = await this.requireReader().readExactly(2, this.scanTimeout);
+          const dataLength = dataLengthBytes.readUInt16LE(0);
+          const imageNumber = metadata.length >= 2 ? metadata.readUInt16LE(0) : 0;
+          const imageChunks = wrappedChunks.get(imageNumber) ?? [];
+          imageChunks.push(await this.requireReader().readExactly(dataLength, this.scanTimeout));
+          wrappedChunks.set(imageNumber, imageChunks);
+          const imageBytes = (wrappedPageBytes.get(imageNumber) ?? 0) + dataLength;
+          wrappedPageBytes.set(imageNumber, imageBytes);
+          if (imageBytes > MAX_PAGE_BYTES) {
+            throw new BrotherScanError('Brother scanner page exceeded the safety limit', 'invalid-response');
+          }
+        } else {
+          chunks.push(await this.requireReader().readExactly(firstLength, this.scanTimeout));
+          pageBytes += firstLength;
+          if (pageBytes > MAX_PAGE_BYTES) {
+            throw new BrotherScanError('Brother scanner page exceeded the safety limit', 'invalid-response');
+          }
+        }
+        continue;
+      }
+
+      if (header === 0x84 || header === 0x85) {
+        await this.requireReader().readExactly(1, this.scanTimeout);
+        continue;
+      }
+
+      if (header === 0x81) {
+        this.finishPage(chunks, pages);
+        chunks = [];
+        pageBytes = 0;
+        frameMode = undefined;
+        await this.writeCommand(['\x1bX']);
+        continue;
+      }
+
+      if (header === 0x82) {
+        const metadata = await this.requireReader().readExactly(9, this.scanTimeout);
+        const imageNumber = metadata.readUInt16LE(2);
+        let imageChunks = wrappedChunks.get(imageNumber);
+        let resolvedImageNumber = imageNumber;
+        if (!imageChunks && wrappedChunks.size === 1) {
+          const onlyImage = wrappedChunks.entries().next().value as [number, Buffer[]];
+          resolvedImageNumber = onlyImage[0];
+          imageChunks = onlyImage[1];
+        }
+        const page = this.makePage(imageChunks ?? []);
+        if (page) wrappedPages.set(resolvedImageNumber, page);
+        wrappedChunks.delete(resolvedImageNumber);
+        wrappedPageBytes.delete(resolvedImageNumber);
+        frameMode = undefined;
+        continue;
+      }
+
+      if (header === TERMINATOR) {
+        this.finishPage(chunks, pages);
+        for (const [imageNumber, imageChunks] of wrappedChunks) {
+          const page = this.makePage(imageChunks);
+          if (page) wrappedPages.set(imageNumber, page);
+        }
+        pages.push(...[...wrappedPages.entries()]
+          .sort(([left], [right]) => left - right)
+          .map(([, page]) => page));
+        return pages;
+      }
+
+      throw this.statusError(header, 'Brother scanner stopped the scan');
+    }
+
+    throw new BrotherScanError(`Brother scanner exceeded the ${MAX_PAGES}-page safety limit`, 'invalid-response');
+  }
+
+  private finishPage(chunks: Buffer[], pages: Buffer[]): void {
+    const page = this.makePage(chunks);
+    if (page) pages.push(page);
+  }
+
+  private makePage(chunks: Buffer[]): Buffer | undefined {
+    if (chunks.length === 0) return undefined;
+    const page = Buffer.concat(chunks);
+    if (page[0] !== 0xff || page[1] !== 0xd8) {
+      const firstBytes = page.subarray(0, 8).toString('hex');
+      const lastBytes = page.subarray(Math.max(0, page.length - 8)).toString('hex');
+      throw new BrotherScanError(
+        `Brother scanner returned an invalid JPEG page (${page.length} bytes, first ${firstBytes}, last ${lastBytes})`,
+        'invalid-response'
+      );
+    }
+
+    const endMarker = page.lastIndexOf(Buffer.from([0xff, 0xd9]));
+    return endMarker >= 0
+      ? page.subarray(0, endMarker + 2)
+      : Buffer.concat([page, Buffer.from([0xff, 0xd9])]);
+  }
+
+  private statusError(status: number, prefix: string): BrotherScanError {
+    if (status === 0xc2) return new BrotherScanError(`${prefix}: no document in feeder`, 'no-document', status);
+    if (status === 0xc3) return new BrotherScanError(`${prefix}: document jam`, 'document-jam', status);
+    if (status === 0xc4) return new BrotherScanError(`${prefix}: cover open`, 'cover-open', status);
+    if (status === 0xc5) return new BrotherScanError(`${prefix}: service error`, 'service-error', status);
+    if (status === 0xc6) {
+      return new BrotherScanError(`${prefix}: device is stuck and must be restarted`, 'device-stuck', status);
+    }
+    if (status === 0x83 || status === 0x86 || status === 0xe3) {
+      return new BrotherScanError(`${prefix}: cancelled`, 'cancelled', status);
+    }
+    return new BrotherScanError(`${prefix}: status 0x${status.toString(16)}`, 'invalid-response', status);
+  }
+
+  private async writeCommand(lines: string[]): Promise<void> {
+    const command = `${lines.join('\n')}\n`;
+    await this.write(Buffer.concat([Buffer.from(command, 'ascii'), Buffer.from([TERMINATOR])]));
+  }
+
+  private async write(data: Buffer): Promise<void> {
+    const socket = this.socket;
+    if (!socket || socket.destroyed) {
+      throw new BrotherScanError('Brother scanner is not connected', 'invalid-response');
+    }
+    await new Promise<void>((resolve, reject) => {
+      socket.write(data, (error) => error ? reject(error) : resolve());
+    });
+  }
+
+  private requireReader(): SocketBuffer {
+    if (!this.reader) throw new BrotherScanError('Brother scanner is not connected', 'invalid-response');
+    return this.reader;
+  }
+}
+
+function delay(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function readJpegMetadata(data: Buffer): { width?: number; height?: number; resolution?: number } {
+  if (data.length < 4 || data[0] !== 0xff || data[1] !== 0xd8) return {};
+  const metadata: { width?: number; height?: number; resolution?: number } = {};
+  const startOfFrameMarkers = new Set([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]);
+  let offset = 2;
+  while (offset + 4 <= data.length) {
+    while (offset < data.length && data[offset] === 0xff) offset++;
+    const marker = data[offset++];
+    if (marker === 0xd9 || marker === 0xda) break;
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+    if (offset + 2 > data.length) break;
+    const length = data.readUInt16BE(offset);
+    if (length < 2 || offset + length > data.length) break;
+    const content = offset + 2;
+    if (marker === 0xe0 && length >= 16 && data.toString('ascii', content, content + 5) === 'JFIF\0') {
+      const units = data[content + 7];
+      const density = data.readUInt16BE(content + 8);
+      if (units === 1 && density > 0) metadata.resolution = density;
+      if (units === 2 && density > 0) metadata.resolution = Math.round(density * 2.54);
+    }
+    if (startOfFrameMarkers.has(marker) && length >= 7) {
+      metadata.height = data.readUInt16BE(content + 1);
+      metadata.width = data.readUInt16BE(content + 3);
+    }
+    offset += length;
+  }
+  return metadata;
+}