@juzi/wechaty-puppet-service 1.0.0

package/src/deprecated/file-box-chunk.ts

@@ -0,0 +1,87 @@
+import { FileBox }      from 'file-box'
+import type { FileBoxInterface } from 'file-box'
+import { PassThrough }  from 'stream'
+import {
+  Readable,
+  Transform,
+}                       from 'stronger-typed-streams'
+
+import { puppet } from '@juzi/wechaty-grpc'
+
+import { nextData } from './next-data.js'
+
+/**
+ * @deprecated Will be removed after Dec 31, 2022
+ */
+const decoder = () => new Transform<puppet.FileBoxChunk, any>({
+  objectMode: true,
+  transform: (chunk: puppet.FileBoxChunk, _: any, callback: any) => {
+    if (!chunk.hasData()) {
+      callback(new Error('no data'))
+      return
+    }
+    const data = chunk.getData()
+    callback(null, data)
+  },
+})
+
+/**
+ * @deprecated Will be removed after Dec 31, 2022
+ */
+async function unpackFileBoxFromChunk (
+  stream: Readable<puppet.FileBoxChunk>,
+): Promise<FileBox> {
+  const chunk = await nextData(stream)
+  if (!chunk.hasName()) {
+    throw new Error('no name')
+  }
+  const fileName = chunk.getName()
+
+  const fileStream = new PassThrough({ objectMode: true })
+  const transformedStream = stream.pipe(decoder())
+  transformedStream.pipe(fileStream)
+  stream.on('error', e => fileStream.emit('error', e))
+  transformedStream.on('error', e => fileStream.emit('error', e))
+
+  const fileBox = FileBox.fromStream(fileStream, fileName)
+
+  return fileBox
+}
+
+/**
+ * @deprecated Will be removed after Dec 31, 2022
+ */
+const encoder = () => new Transform<any, puppet.FileBoxChunk>({
+  objectMode: true,
+  transform: (chunk: any, _: any, callback: any) => {
+    const fileBoxChunk = new puppet.FileBoxChunk()
+    fileBoxChunk.setData(chunk)
+    callback(null, fileBoxChunk)
+  },
+})
+
+/**
+ * @deprecated Will be removed after Dec 31, 2022
+ */
+async function packFileBoxToChunk (
+  fileBox: FileBoxInterface,
+): Promise<Readable<puppet.FileBoxChunk>> {
+  const stream = new PassThrough({ objectMode: true })
+
+  const chunk = new puppet.FileBoxChunk()
+  chunk.setName(fileBox.name)
+
+  // FIXME: Huan(202010) write might return false
+  stream.write(chunk)
+
+  fileBox
+    .pipe(encoder())
+    .pipe(stream)
+
+  return stream
+}
+
+export {
+  unpackFileBoxFromChunk,
+  packFileBoxToChunk,
+}

package/src/deprecated/file-box-pb.spec.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+
+import { test } from 'tstest'
+
+import { FileBox } from 'file-box'
+
+import {
+  puppet,
+}                                 from '@juzi/wechaty-grpc'
+
+import {
+  packFileBoxToPb,
+  unpackFileBoxFromPb,
+}                             from './file-box-pb.js'
+
+test('packFileBoxToPb()', async t => {
+  const FILE_BOX_DATA = 'test'
+  const FILE_BOX_NAME = 'test.dat'
+
+  const fileBox = FileBox.fromBuffer(
+    Buffer.from(FILE_BOX_DATA),
+    FILE_BOX_NAME,
+  )
+
+  const pb = await packFileBoxToPb(puppet.MessageFileStreamResponse)(fileBox)
+  const restoredFileBox = await unpackFileBoxFromPb(pb)
+  t.ok(restoredFileBox instanceof FileBox, 'should get an instance of FileBOX')
+
+  t.equal(restoredFileBox.name, fileBox.name, 'should get the right file box name')
+  t.equal(await restoredFileBox.toBase64(), await fileBox.toBase64(), 'should get the right file box content')
+})

package/src/deprecated/file-box-pb.ts

@@ -0,0 +1,41 @@
+import type { FileBoxInterface }      from 'file-box'
+import type { Readable }     from 'stronger-typed-streams'
+
+import {
+  packFileBoxToChunk,
+  unpackFileBoxFromChunk,
+}                           from './file-box-chunk.js'
+import {
+  packFileBoxChunkToPb,
+  unpackFileBoxChunkFromPb,
+}                           from './chunk-pb.js'
+import type { FileBoxPb }        from './file-box-pb.type.js'
+
+/**
+ * @deprecated Will be removed after Dec 31, 2022
+ */
+function packFileBoxToPb<T extends FileBoxPb> (
+  PbConstructor: { new(): T },
+) {
+  return async (fileBox: FileBoxInterface) => {
+    const fileBoxChunkStream = await packFileBoxToChunk(fileBox)
+    const pbFileBox = packFileBoxChunkToPb(PbConstructor)(fileBoxChunkStream)
+    return pbFileBox
+  }
+}
+
+/**
+ * @deprecated Will be removed after Dec 31, 2022
+ */
+async function unpackFileBoxFromPb<T extends FileBoxPb> (
+  pbStream: Readable<T>,
+): Promise<FileBoxInterface> {
+  const fileBoxChunkStream = unpackFileBoxChunkFromPb(pbStream)
+  const fileBox = await unpackFileBoxFromChunk(fileBoxChunkStream)
+  return fileBox
+}
+
+export {
+  packFileBoxToPb,
+  unpackFileBoxFromPb,
+}

package/src/deprecated/file-box-pb.type.ts

@@ -0,0 +1,16 @@
+import type { puppet } from '@juzi/wechaty-grpc'
+
+/**
+ * Any Protocol Buffer message that include a FileBoxChunk
+ */
+export interface FileBoxPb {
+  hasFileBoxChunk(): boolean
+  getFileBoxChunk(): puppet.FileBoxChunk | undefined
+  setFileBoxChunk(value?: puppet.FileBoxChunk): void
+}
+
+export interface ConversationIdFileBoxPb extends FileBoxPb {
+  hasConversationId(): boolean
+  getConversationId(): string
+  setConversationId(value: string): void
+}

package/src/deprecated/mod.ts

@@ -0,0 +1,8 @@
+export {
+  packConversationIdFileBoxToPb,
+  unpackConversationIdFileBoxArgsFromPb,
+}                                         from './conversation-id-file-box.js'
+export {
+  packFileBoxToPb,
+  unpackFileBoxFromPb,
+}                                         from './file-box-pb.js'

package/src/deprecated/next-data.ts

@@ -0,0 +1,35 @@
+import type {
+  Readable,
+}           from 'stronger-typed-streams'
+
+/**
+ * windmemory(20201027): generating fileBox data in server side might take longer.
+ * Set to 60 sec to avoid unexpected timeout.
+ */
+const TIMEOUT = 60 * 1000
+
+/**
+ * @deprecated Will be removed after Dec 31, 2022
+ */
+async function nextData<T> (
+  stream: Readable<T>,
+): Promise<T> {
+  const chunk = await new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(reject, TIMEOUT)
+    stream.once('data', chunk => {
+      stream.pause()
+      clearTimeout(timer)
+
+      resolve(chunk)
+    })
+    stream.once('error', reject)
+
+  })
+
+  stream.resume()
+  return chunk
+}
+
+export {
+  nextData,
+}

package/src/deprecated/serialize-file-box.ts

@@ -0,0 +1,24 @@
+import {
+  FileBox,
+  FileBoxType,
+}                     from 'file-box'
+import type {
+  FileBoxInterface,
+}                     from 'file-box'
+
+/**
+ * @deprecated Will be removed after Dec 31, 2022
+ */
+export const serializeFileBox = async (fileBox: FileBoxInterface): Promise<string> => {
+  const serializableFileBoxTypes = [
+    FileBoxType.Base64,
+    FileBoxType.Url,
+    FileBoxType.QRCode,
+  ]
+  if (serializableFileBoxTypes.includes(fileBox.type)) {
+    return JSON.stringify(fileBox)
+  }
+  const base64 = await fileBox.toBase64()
+  const name = fileBox.name
+  return JSON.stringify(FileBox.fromBase64(base64, name))
+}

package/src/env-vars.spec.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+
+// tslint:disable:no-shadowed-variable
+import { test }  from 'tstest'
+
+import { WECHATY_PUPPET_SERVICE_AUTHORITY } from './env-vars.js'
+
+/**
+ * Huan(202108): compatible with old env var
+ *  See: https://github.com/wechaty/wechaty-puppet-service/issues/156
+ *
+ * This feature will be removed after Dec 31, 2022
+ */
+test('WECHATY_PUPPET_SERVICE_AUTHORITY()', async t => {
+  const EXPECTED_AUTHORITY = 'api.wechaty.io'
+  const oldValue = process.env['WECHATY_SERVICE_DISCOVERY_ENDPOINT']
+  process.env['WECHATY_SERVICE_DISCOVERY_ENDPOINT'] = `https://${EXPECTED_AUTHORITY}`
+
+  const result = WECHATY_PUPPET_SERVICE_AUTHORITY()
+  t.equal(result, EXPECTED_AUTHORITY, 'should extract authority')
+
+  process.env['WECHATY_SERVICE_DISCOVERY_ENDPOINT'] = oldValue
+})

package/src/env-vars.ts

@@ -0,0 +1,100 @@
+import { log } from '@juzi/wechaty-puppet'
+
+// Huan(202011): use a function to return the value in time.
+const WECHATY_PUPPET_SERVICE_TOKEN: (token?: string) => string = token => {
+  if (token) {
+    return token
+  }
+
+  if (process.env['WECHATY_PUPPET_SERVICE_TOKEN']) {
+    return process.env['WECHATY_PUPPET_SERVICE_TOKEN']
+  }
+
+  /**
+   * Huan(202102): remove this deprecated warning after Dec 31, 2021
+   */
+  if (process.env['WECHATY_PUPPET_HOSTIE_TOKEN']) {
+    log.warn('wechaty-puppet-service', [
+      '',
+      'WECHATY_PUPPET_HOSTIE_TOKEN has been deprecated,',
+      'please use WECHATY_PUPPET_SERVICE_TOKEN instead.',
+      'See: https://github.com/wechaty/wechaty-puppet-service/issues/118',
+      '',
+    ].join(' '))
+    return process.env['WECHATY_PUPPET_HOSTIE_TOKEN']
+  }
+
+  const tokenNotFoundError = 'wechaty-puppet-service: WECHATY_PUPPET_SERVICE_TOKEN not found'
+
+  console.error([
+    '',
+    tokenNotFoundError,
+    '(save token to WECHATY_PUPPET_SERVICE_TOKEN env var or pass it to puppet options is required.).',
+    '',
+    'To learn how to get Wechaty Puppet Service Token,',
+    'please visit <https://wechaty.js.org/docs/puppet-services/>',
+    'to see our Wechaty Puppet Service Providers.',
+    '',
+  ].join('\n'))
+
+  throw new Error(tokenNotFoundError)
+}
+
+const WECHATY_PUPPET_SERVICE_ENDPOINT = (endpoint?: string) => {
+  if (endpoint) {
+    return endpoint
+  }
+
+  if (process.env['WECHATY_PUPPET_SERVICE_ENDPOINT']) {
+    return process.env['WECHATY_PUPPET_SERVICE_ENDPOINT']
+  }
+  /**
+   * Huan(202102): remove this deprecated warning after Dec 31, 2021
+   */
+  if (process.env['WECHATY_PUPPET_HOSTIE_ENDPOINT']) {
+    log.warn('wechaty-puppet-service', [
+      '',
+      'WECHATY_PUPPET_HOSTIE_ENDPOINT has been deprecated,',
+      'please use WECHATY_PUPPET_SERVICE_ENDPOINT instead.',
+      'See: https://github.com/wechaty/wechaty-puppet-service/issues/118',
+      '',
+    ].join(' '))
+    return process.env['WECHATY_PUPPET_HOSTIE_ENDPOINT']
+  }
+
+  return undefined
+}
+
+const WECHATY_PUPPET_SERVICE_AUTHORITY = (authority?: string) => {
+  if (authority) {
+    return authority
+  }
+
+  authority = process.env['WECHATY_PUPPET_SERVICE_AUTHORITY']
+  if (authority) {
+    return authority
+  }
+
+  const deprecatedDiscoveryEndpoint = process.env['WECHATY_SERVICE_DISCOVERY_ENDPOINT']
+  if (deprecatedDiscoveryEndpoint) {
+    console.error([
+      'Environment variable WECHATY_SERVICE_DISCOVERY_ENDPOINT is deprecated,',
+      'Use WECHATY_PUPPET_SERVICE_AUTHORITY instead.',
+      'See: https://github.com/wechaty/wechaty-puppet-service/issues/156',
+    ].join('\n'))
+    return deprecatedDiscoveryEndpoint
+      .replace(/^https?:\/\//, '')
+      .replace(/\/*$/, '')
+  }
+
+  /**
+   * Huan(202108): Wechaty community default authority
+   */
+  return 'api.chatie.io'
+}
+
+export {
+  WECHATY_PUPPET_SERVICE_ENDPOINT,
+  WECHATY_PUPPET_SERVICE_TOKEN,
+  WECHATY_PUPPET_SERVICE_AUTHORITY,
+}

package/src/event-type-rev.ts

@@ -0,0 +1,19 @@
+import {
+  puppet,
+}               from '@juzi/wechaty-grpc'
+
+/**
+ * Huan(202003):
+ *  @chatie/GRPC proto gen TS does not generate the ENUM type with reverse mapping.
+ *  So we need to do it by ourselves:
+ *    1. define the EventTypeRev, and
+ *    2. loop EventType to fill it.
+ */
+export const EventTypeRev = {} as {
+  [key: number]: string,
+}
+
+for (const key in puppet.EventType) {
+  const val = puppet.EventType[key as keyof puppet.EventTypeMap]
+  EventTypeRev[val] = key
+}

package/src/file-box-helper/mod.ts

@@ -0,0 +1,11 @@
+import {
+  uuidifyFileBoxGrpc,
+}                         from './uuidify-file-box-grpc.js'
+import {
+  normalizeFileBoxUuid,
+}                         from './normalize-filebox.js'
+
+export {
+  normalizeFileBoxUuid,
+  uuidifyFileBoxGrpc,
+}

package/src/file-box-helper/normalize-filebox.spec.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+
+import { test }  from 'tstest'
+import { FileBox } from 'file-box'
+
+import { canPassthrough } from './normalize-filebox.js'
+
+const kbFileBox = (size: number) => FileBox.fromBuffer(Buffer.from(
+  new Int8Array(size * 1024).fill(0),
+), size + 'KB.txt')
+
+test('canPassthrough() size threshold', async t => {
+  t.ok(canPassthrough(kbFileBox(16)),     'should passthrough 16KB')
+  t.notOk(canPassthrough(kbFileBox(32)),  'should not passthrough 32KB')
+})
+
+test('canPassthrough(): always true for green types', async t => {
+  const URL    = 'https://example.com'
+  const QRCODE = 'qrcode'
+  const UUID   = '12345678-1234-5678-1234-567812345678'
+
+  t.ok(canPassthrough(FileBox.fromUrl(URL)),        'should passthrough Url')
+  t.ok(canPassthrough(FileBox.fromQRCode(QRCODE)),  'should passthrough QRCode')
+  t.ok(canPassthrough(FileBox.fromUuid(UUID)),      'should passthrough UUID')
+})
+
+test('canPassthrough(): always false for red types', async t => {
+  const streamFileBox = FileBox.fromStream(
+    await FileBox.fromQRCode('qr').toStream(),
+  )
+  const localFileBox = FileBox.fromFile('tests/fixtures/smoke-testing.ts')
+
+  t.notOk(canPassthrough(streamFileBox),  'should not passthrough Stream')
+  t.notOk(canPassthrough(localFileBox),   'should not passthrough File')
+})
+
+test('canPassthrough(): will depend on the size for yellow types', async t => {
+  const bufferFileBox = FileBox.fromBuffer(Buffer.from('buf'))
+  const base64FileBox = FileBox.fromBase64(Buffer.from('buf').toString('base64'))
+
+  t.ok(canPassthrough(bufferFileBox), 'should not passthrough small Buffer')
+  t.ok(canPassthrough(base64FileBox), 'should not passthrough small Base64')
+
+  /**
+   * TODO: add the large size test which will over the threshold
+   */
+})

package/src/file-box-helper/normalize-filebox.ts

@@ -0,0 +1,90 @@
+import type {
+  FileBox,
+}                     from 'file-box'
+import {
+  FileBoxType,
+  FileBoxInterface,
+}                     from 'file-box'
+
+/**
+ * Huan(202110): for testing propose, use 20KB as the threshold
+ *  after stable we should use a value between 64KB to 256KB as the threshold
+ */
+const PASS_THROUGH_THRESHOLD_BYTES = 20 * 1024 // 20KB
+
+/**
+ * 1. Green:
+ *  Can be serialized directly
+ */
+const greenFileBoxTypes = [
+  FileBoxType.Url,
+  FileBoxType.Uuid,
+  FileBoxType.QRCode,
+]
+/**
+ * 2. Yellow:
+ *  Can be serialized directly, if the size is less than a threshold
+ *  if it's bigger than the threshold,
+ *  then it should be convert to a UUID file box before send out
+ */
+const yellowFileBoxTypes = [
+  FileBoxType.Buffer,
+  FileBoxType.Base64,
+]
+
+const canPassthrough = (fileBox: FileBoxInterface) => {
+  /**
+   * 1. Green types: YES
+   */
+  if (greenFileBoxTypes.includes(fileBox.type)) {
+    return true
+  }
+
+  /**
+   * 2. Red types: NO
+   */
+  if (!yellowFileBoxTypes.includes(fileBox.type)) {
+    return false
+  }
+
+  /**
+   * 3. Yellow types: CHECK size
+   */
+  const size = fileBox.size
+  if (size < 0) {
+    // 1. Size unknown: NO
+    return false
+  } else if (size > PASS_THROUGH_THRESHOLD_BYTES) {
+    // 2. Size: bigger than threshold: NO
+    return false
+  } else {
+    // 3. Size: smaller than threshold: YES
+    return true
+  }
+
+}
+
+const normalizeFileBoxUuid = (FileBoxUuid: typeof FileBox) => async (fileBox: FileBoxInterface) => {
+  if (canPassthrough(fileBox)) {
+    return fileBox
+  }
+
+  const stream = await fileBox.toStream()
+
+  const uuid = await FileBoxUuid
+    .fromStream(stream, fileBox.name)
+    .toUuid()
+
+  const uuidFileBox = FileBoxUuid.fromUuid(uuid, {
+    md5  : fileBox.md5,
+    name : fileBox.name,
+    size : fileBox.size,
+  })
+
+  return uuidFileBox
+}
+
+export {
+  canPassthrough,
+  normalizeFileBoxUuid,
+}

package/src/file-box-helper/uuidify-file-box-grpc.ts

@@ -0,0 +1,83 @@
+import type {
+  Readable,
+  Writable,
+}                       from 'stream'
+
+import {
+  FileBox,
+  UuidLoader,
+  UuidSaver,
+}                         from 'file-box'
+import {
+  chunkDecoder,
+  chunkEncoder,
+  puppet as pbPuppet,
+}                         from '@juzi/wechaty-grpc'
+import {
+  cloneClass,
+  Constructor,
+}                         from 'clone-class'
+
+const uuidResolverGrpc: (grpcClient: () => pbPuppet.PuppetClient) => UuidLoader = (
+  grpcClient,
+) => async function uuidResolver (
+  this : FileBox,
+  uuid : string,
+) {
+  const request = new pbPuppet.DownloadRequest()
+  request.setId(uuid)
+
+  const response = grpcClient().download(request)
+
+  const stream = response
+    .pipe(chunkDecoder())
+
+  return stream
+}
+
+const uuidRegisterGrpc: (grpcClient: () => pbPuppet.PuppetClient) => UuidSaver = (
+  grpcClient,
+) => async function uuidRegister (
+  this   : FileBox,
+  stream : Readable,
+) {
+  const response = await new Promise<pbPuppet.UploadResponse>((resolve, reject) => {
+    const request = grpcClient().upload((err, response) => {
+      if (err) {
+        reject(err)
+      } else {
+        resolve(response)
+      }
+    }) as unknown as Writable  // Huan(202203) FIXME: as unknown as
+
+    stream
+      .pipe(chunkEncoder(pbPuppet.UploadRequest))
+      .pipe(request)
+  })
+
+  const uuid = response.getId()
+  return uuid
+}
+
+type UuidifyFileBoxGrpcFactory = (grpcClient: () => pbPuppet.PuppetClient) => typeof FileBox
+
+const uuidifyFileBoxGrpc: UuidifyFileBoxGrpcFactory = (
+  grpcClient,
+) => {
+  /**
+   * `as any`:
+   *
+   * Huan(202110): TypeError: Cannot read property 'valueDeclaration' of undefined #58
+   *  https://github.com/huan/clone-class/issues/58
+   */
+  const FileBoxUuid: typeof FileBox = cloneClass(FileBox as any as Constructor<FileBox>) as any
+
+  FileBoxUuid.setUuidLoader(uuidResolverGrpc(grpcClient))
+  FileBoxUuid.setUuidSaver(uuidRegisterGrpc(grpcClient))
+
+  return FileBoxUuid
+}
+
+export {
+  uuidifyFileBoxGrpc,
+}

package/src/file-box-helper/uuidify-file-box-local.ts

@@ -0,0 +1,31 @@
+import {
+  FileBox,
+  UniformResourceNameRegistry,
+}                               from 'file-box'
+import {
+  cloneClass,
+  Constructor,
+}                               from 'clone-class'
+
+type UuidifyFileBoxLocalFactory = (urnRegistry: UniformResourceNameRegistry) => typeof FileBox
+
+const uuidifyFileBoxLocal: UuidifyFileBoxLocalFactory = (
+  urnRegistry,
+) => {
+  /**
+   * `as any`:
+   *
+   * Huan(202110): TypeError: Cannot read property 'valueDeclaration' of undefined #58
+   *  https://github.com/huan/clone-class/issues/58
+   */
+  const FileBoxUuid: typeof FileBox = cloneClass(FileBox as any as Constructor<FileBox>) as any
+
+  FileBoxUuid.setUuidLoader(uuid   => urnRegistry.load(uuid))
+  FileBoxUuid.setUuidSaver(stream  => urnRegistry.save(stream))
+
+  return FileBoxUuid
+}
+
+export {
+  uuidifyFileBoxLocal,
+}

package/src/mod.spec.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+
+import { test }  from 'tstest'
+
+import * as mod from './mod.js'
+
+test('default export', async t => {
+  t.equal(typeof mod.default, 'function', 'should export Puppet class as default, which is required from PuppetManager of Wechaty')
+})

package/src/mod.ts

@@ -0,0 +1,25 @@
+import {
+  log,
+}                 from '@juzi/wechaty-puppet'
+import {
+  PuppetService,
+}                 from './client/puppet-service.js'
+import {
+  VERSION,
+}                 from './config.js'
+import {
+  PuppetServer,
+  PuppetServerOptions,
+}                         from './server/puppet-server.js'
+
+export {
+  log,
+  PuppetServer,
+  PuppetService,
+  VERSION,
+}
+export type {
+  PuppetServerOptions,
+}
+
+export default PuppetService