memx 0.0.1

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "memx",
+  "version": "0.0.1",
+  "description": "Simple and fast memcached client",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "scripts": {
+    "build": "./build.sh",
+    "dev": "nodemon -e ts -x ./build.sh -w src -w test",
+    "lint": "eslint src test",
+    "prepare": "patch -N -p0 -i .nyc.patch || true"
+  },
+  "author": "Juit Developers <developers@juit.com>",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.19.4",
+    "@types/chai": "^4.3.0",
+    "@types/chai-as-promised": "^7.1.5",
+    "@types/memjs": "^1.2.4",
+    "@types/mocha": "^9.1.0",
+    "@types/node": "~16.11.26",
+    "@types/source-map-support": "^0.5.4",
+    "@typescript-eslint/eslint-plugin": "^5.14.0",
+    "@typescript-eslint/parser": "^5.14.0",
+    "chai": "^4.3.6",
+    "chai-as-promised": "^7.1.1",
+    "chai-exclude": "^2.1.0",
+    "esbuild": "^0.14.25",
+    "eslint": "^8.10.0",
+    "eslint-config-google": "^0.14.0",
+    "memjs": "^1.3.0",
+    "mocha": "^9.2.1",
+    "nodemon": "^2.0.15",
+    "nyc": "^15.1.0",
+    "source-map-support": "^0.5.21",
+    "typescript": "^4.6.2"
+  },
+  "directories": {
+    "test": "test"
+  }
+}

package/src/buffers.ts

@@ -0,0 +1,27 @@
+import { BUFFERS } from './constants'
+
+const pool: Buffer[] = new Array(BUFFERS.POOL_SIZE)
+let offset = -1
+
+export interface RecyclableBuffer extends Buffer {
+  recycle(): void
+}
+
+export function allocateBuffer(size: number): RecyclableBuffer {
+  if (size > BUFFERS.BUFFER_SIZE) {
+    const buffer = Buffer.allocUnsafeSlow(size) as RecyclableBuffer
+    buffer.recycle = () => void 0
+    return buffer
+  }
+
+  const buffer = offset >= 0 ? pool[offset--] : Buffer.allocUnsafeSlow(BUFFERS.BUFFER_SIZE)
+  const recyclable = buffer.subarray(0, size) as RecyclableBuffer
+  let recycled = false
+  recyclable.recycle = (): void => queueMicrotask(() => {
+    if ((offset >= BUFFERS.POOL_SIZE) || recycled) return
+    pool[++offset] = buffer
+    recycled = true
+  })
+
+  return recyclable as RecyclableBuffer
+}

package/src/client.ts

@@ -0,0 +1,228 @@
+import assert from 'assert'
+import { isTypedArray } from 'util/types'
+
+import { ClusterAdapter, ClusterOptions } from './cluster'
+import { EMPTY_BUFFER, FLAGS } from './constants'
+import { typedArrayFlags } from './internals'
+import { Adapter, Counter, Stats } from './types'
+
+function toBuffer<T>(value: any, options: T): [ Buffer, T & { flags: number } ] {
+  if (Buffer.isBuffer(value)) return [ value, { ...options, flags: FLAGS.BUFFER } ]
+
+  switch (typeof value) {
+    case 'bigint':
+      return [ Buffer.from(value.toString(), 'utf-8'), { ...options, flags: FLAGS.BIGINT } ]
+    case 'boolean':
+      return [ Buffer.alloc(1, value ? 0xff : 0x00), { ...options, flags: FLAGS.BOOLEAN } ]
+    case 'number':
+      return [ Buffer.from(value.toString(), 'utf-8'), { ...options, flags: FLAGS.NUMBER } ]
+    case 'string':
+      return [ Buffer.from(value, 'utf-8'), { ...options, flags: FLAGS.STRING } ]
+    case 'object':
+      break // more checks below...
+    default:
+      assert.fail(`Unable to store value of type "${typeof value}"`)
+  }
+
+  // typed arrays are special
+  if (isTypedArray(value)) {
+    const flags = typedArrayFlags(value)
+    const buffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+    return [ buffer, { ...options, flags } ]
+  }
+
+  // null is also special...
+  if (value === null) return [ EMPTY_BUFFER, { ...options, flags: FLAGS.NULL } ]
+
+  // any other "object" gets serialized as JSON
+  return [ Buffer.from(JSON.stringify(value), 'utf-8'), { ...options, flags: FLAGS.JSON } ]
+}
+
+function makeTypedArray<T extends NodeJS.TypedArray>(
+  constructor: new (buffer: ArrayBuffer, offset?: number, length?: number) => T,
+  source: Buffer,
+  bytesPerValue: number,
+): T {
+  const clone = Buffer.from(source)
+  const { buffer, byteOffset, byteLength } = clone
+  return new constructor(buffer, byteOffset, byteLength / bytesPerValue)
+}
+
+export type Serializable = bigint | string | number | boolean | null | object
+export type Appendable = string | NodeJS.TypedArray
+
+export interface ClientResult<T extends Serializable> {
+  value: T
+  cas: bigint
+}
+
+export class Client {
+  #adapter!: Adapter
+
+  constructor()
+  constructor(adapter: Adapter)
+  constructor(options: ClusterOptions)
+
+  constructor(adapterOrOptions?: Adapter | ClusterOptions) {
+    if (! adapterOrOptions) {
+      this.#adapter = new ClusterAdapter()
+    } else if ('get' in adapterOrOptions) {
+      this.#adapter = adapterOrOptions
+    } else if ('hosts' in adapterOrOptions) {
+      this.#adapter = new ClusterAdapter(adapterOrOptions)
+    }
+
+    assert(this.#adapter, 'Invalid client constructor arguments')
+  }
+
+  get adapter(): Adapter {
+    return this.#adapter
+  }
+
+  async get<T extends Serializable>(key: string, options?: { ttl?: number }): Promise<ClientResult<T> | void> {
+    const result = await this.#adapter.get(key, options)
+    if (! result) return
+
+    try {
+      const { flags, value, cas } = result
+      switch (flags) {
+        case FLAGS.BIGINT:
+          return { value: BigInt(value.toString('utf-8')) as T, cas }
+        case FLAGS.BOOLEAN:
+          return { value: !!value[0] as T, cas }
+        case FLAGS.NUMBER:
+          return { value: Number(value.toString('utf-8' )) as T, cas }
+        case FLAGS.STRING:
+          return { value: value.toString('utf-8' ) as T, cas }
+
+        case FLAGS.NULL:
+          return { value: null as T, cas }
+        case FLAGS.JSON:
+          return { value: JSON.parse(value.toString('utf-8' )) as T, cas }
+
+        case FLAGS.UINT8ARRAY:
+          return { value: makeTypedArray(Uint8Array, value, 1) as T, cas }
+        case FLAGS.UINT8CLAMPEDARRAY:
+          return { value: makeTypedArray(Uint8ClampedArray, value, 1) as T, cas }
+        case FLAGS.UINT16ARRAY:
+          return { value: makeTypedArray(Uint16Array, value, 2) as T, cas }
+        case FLAGS.UINT32ARRAY:
+          return { value: makeTypedArray(Uint32Array, value, 4) as T, cas }
+        case FLAGS.INT8ARRAY:
+          return { value: makeTypedArray(Int8Array, value, 1) as T, cas }
+        case FLAGS.INT16ARRAY:
+          return { value: makeTypedArray(Int16Array, value, 2) as T, cas }
+        case FLAGS.INT32ARRAY:
+          return { value: makeTypedArray(Int32Array, value, 4) as T, cas }
+        case FLAGS.BIGUINT64ARRAY:
+          return { value: makeTypedArray(BigUint64Array, value, 8) as T, cas }
+        case FLAGS.BIGINT64ARRAY:
+          return { value: makeTypedArray(BigInt64Array, value, 8) as T, cas }
+        case FLAGS.FLOAT32ARRAY:
+          return { value: makeTypedArray(Float32Array, value, 4) as T, cas }
+        case FLAGS.FLOAT64ARRAY:
+          return { value: makeTypedArray(Float64Array, value, 8) as T, cas }
+
+        case FLAGS.BUFFER:
+        default:
+          return { value: Buffer.from(value) as T, cas }
+      }
+    } finally {
+      result.recycle()
+    }
+  }
+
+  async set(key: string, value: Serializable, options?: { cas?: bigint, ttl?: number }): Promise<bigint | void> {
+    return this.#adapter.set(key, ...toBuffer(value, options))
+  }
+
+  async add(key: string, value: Serializable, options?: { cas?: bigint, ttl?: number }): Promise<bigint | void> {
+    return this.#adapter.add(key, ...toBuffer(value, options))
+  }
+
+  async replace(key: string, value: Serializable, options?: { cas?: bigint, ttl?: number }): Promise<bigint | void> {
+    return this.#adapter.replace(key, ...toBuffer(value, options))
+  }
+
+  append(
+    key: string,
+    value: Appendable,
+    options?: { cas?: bigint },
+  ): Promise<boolean> {
+    return this.#adapter.append(key, ...toBuffer(value, options))
+  }
+
+  prepend(
+    key: string,
+    value: Appendable,
+    options?: { cas?: bigint },
+  ): Promise<boolean> {
+    return this.#adapter.prepend(key, ...toBuffer(value, options))
+  }
+
+  async increment(
+    key: string,
+    delta?: bigint | number,
+    options?: { initial?: bigint | number, cas?: bigint, ttl?: number },
+  ): Promise<Counter | void> {
+    const counter = await this.#adapter.increment(key, delta, options)
+
+    if (counter && options &&
+        (options.initial !== undefined) &&
+        (counter.value === BigInt(options.initial))) {
+      const cas = await this.replace(key, counter.value, { cas: counter.cas, ttl: options.ttl })
+      counter.cas = cas ?? counter.cas
+    }
+    return counter
+  }
+
+  async decrement(
+    key: string,
+    delta?: bigint | number,
+    options?: { initial?: bigint | number, cas?: bigint, ttl?: number },
+  ): Promise<Counter | void> {
+    const counter = await this.#adapter.decrement(key, delta, options)
+
+    if (counter && options &&
+        (options.initial !== undefined) &&
+        (counter.value === BigInt(options.initial))) {
+      const cas = await this.replace(key, counter.value, { cas: counter.cas, ttl: options.ttl })
+      counter.cas = cas ?? counter.cas
+    }
+    return counter
+  }
+
+  touch(
+    key: string,
+    options?: { ttl?: number },
+  ): Promise<boolean> {
+    return this.#adapter.touch(key, options)
+  }
+
+  delete(
+    key: string,
+    options?: { cas?: bigint },
+  ): Promise<boolean> {
+    return this.#adapter.delete(key, options)
+  }
+
+  flush(ttl?: number): Promise<void> {
+    return this.#adapter.flush(ttl)
+  }
+
+  noop(): Promise<void> {
+    return this.#adapter.noop()
+  }
+
+  quit(): Promise<void> {
+    return this.#adapter.quit()
+  }
+
+  version(): Promise<Record<string, string>> {
+    return this.#adapter.version()
+  }
+
+  stats(): Promise<Record<string, Stats>> {
+    return this.#adapter.stats()
+  }
+}

package/src/cluster.ts

@@ -0,0 +1,139 @@
+import { Adapter, Counter, AdapterResult, Stats } from './types'
+import { ServerAdapter, ServerOptions } from './server'
+
+function parseHosts(hosts?: string): ServerOptions[] {
+  const result: { host: string, port?: number }[] = []
+  if (! hosts) return result
+
+  for (const part of hosts.split(',')) {
+    const [ host, p ] = part.split(':')
+    const port = parseInt(p) || undefined
+    result.push({ host, port })
+  }
+
+  return result
+}
+
+
+export interface ClusterOptions {
+  hosts: string | string[] | ServerOptions[],
+  timeout?: number,
+  ttl?: number
+}
+
+export class ClusterAdapter implements Adapter {
+  readonly servers: readonly ServerAdapter[]
+
+  constructor()
+  constructor(servers: ServerAdapter[])
+  constructor(options: ClusterOptions)
+
+  constructor(serversOrOptions?: ServerAdapter[] | ClusterOptions) {
+    // If we have an array of servers, just copy it and use it
+    if (Array.isArray(serversOrOptions)) {
+      this.servers = [ ...serversOrOptions ]
+
+    // This was created with "options"... Convert and construct
+    } else if (serversOrOptions) {
+      const { ttl, timeout, hosts: defs } = serversOrOptions
+      const hosts: ServerOptions[] = []
+
+      if (Array.isArray(defs)) {
+        defs.forEach((def) => {
+          if (typeof def === 'string') hosts.push(...parseHosts(def))
+          else hosts.push({ port: 11211, ...def })
+        })
+      } else {
+        hosts.push(...parseHosts(defs))
+      }
+
+      this.servers = hosts.map((host) => new ServerAdapter({ ttl, timeout, ...host }))
+
+    // Anything else gets initialized from environment variables
+    } else {
+      const hosts = parseHosts(process.env.MEMCACHED_HOSTS)
+      const ttl = process.env.MEMCACHED_TTL && parseInt(process.env.MEMCACHED_TTL) || undefined
+      const timeout = process.env.MEMCACHED_TIMEOUT && parseInt(process.env.MEMCACHED_TIMEOUT) || undefined
+
+      this.servers = hosts.map((host) => new ServerAdapter({ ttl, timeout, ...host }))
+    }
+
+    // Validate and shortcut in case of single-servers setup
+    if (this.servers.length < 1) throw new Error('No hosts configured')
+    if (this.servers.length === 1) this.server = (): ServerAdapter => this.servers[0]
+
+    // Freeze our lists of servers
+    Object.freeze(this.servers)
+  }
+
+  server(key: string): ServerAdapter {
+    const length = key.length
+
+    let hash = 0
+    for (let i = 0; i < length; i ++) hash = hash * 31 + key.charCodeAt(i)
+
+    return this.servers[hash % this.servers.length]
+  }
+
+  get(key: string, options?: { ttl?: number | undefined }): Promise<void | AdapterResult> {
+    return this.server(key).get(key, options)
+  }
+
+  touch(key: string, options?: { ttl?: number | undefined }): Promise<boolean> {
+    return this.server(key).touch(key, options)
+  }
+
+  set(key: string, value: Buffer, options?: { flags?: number | undefined; cas?: bigint | undefined; ttl?: number | undefined }): Promise<bigint | void> {
+    return this.server(key).set(key, value, options)
+  }
+
+  add(key: string, value: Buffer, options?: { flags?: number | undefined; cas?: bigint | undefined; ttl?: number | undefined }): Promise<bigint | void> {
+    return this.server(key).add(key, value, options)
+  }
+
+  replace(key: string, value: Buffer, options?: { flags?: number | undefined; cas?: bigint | undefined; ttl?: number | undefined }): Promise<bigint | void> {
+    return this.server(key).replace(key, value, options)
+  }
+
+  append(key: string, value: Buffer, options?: { cas?: bigint | undefined }): Promise<boolean> {
+    return this.server(key).append(key, value, options)
+  }
+
+  prepend(key: string, value: Buffer, options?: { cas?: bigint | undefined }): Promise<boolean> {
+    return this.server(key).prepend(key, value, options)
+  }
+
+  increment(key: string, delta?: number | bigint, options?: { initial?: number | bigint | undefined; cas?: bigint | undefined; ttl?: number | undefined; create?: boolean | undefined }): Promise<void | Counter> {
+    return this.server(key).increment(key, delta, options)
+  }
+
+  decrement(key: string, delta?: number | bigint, options?: { initial?: number | bigint | undefined; cas?: bigint | undefined; ttl?: number | undefined; create?: boolean | undefined }): Promise<void | Counter> {
+    return this.server(key).decrement(key, delta, options)
+  }
+
+  delete(key: string, options?: { cas?: bigint | undefined }): Promise<boolean> {
+    return this.server(key).delete(key, options)
+  }
+
+  async flush(ttl?: number): Promise<void> {
+    await Promise.all(this.servers.map((server) => server.flush(ttl)))
+  }
+
+  async noop(): Promise<void> {
+    await Promise.all(this.servers.map((server) => server.noop()))
+  }
+
+  async quit(): Promise<void> {
+    await Promise.all(this.servers.map((server) => server.quit()))
+  }
+
+  async version(): Promise<Record<string, string>> {
+    const versions = await Promise.all(this.servers.map((server) => server.version()))
+    return versions.reduce((v1, v2) => ({ ...v1, ...v2 }))
+  }
+
+  async stats(): Promise<Record<string, Stats>> {
+    const stats = await Promise.all(this.servers.map((server) => server.stats()))
+    return stats.reduce((v1, v2) => ({ ...v1, ...v2 }))
+  }
+}

package/src/connection.ts

@@ -0,0 +1,191 @@
+import assert from 'assert'
+import net, { Socket } from 'net'
+
+import { Encoder, RawOutgoingPacket } from './encode'
+import { Decoder, RawIncomingPacket } from './decode'
+import { BUFFERS, OPCODE } from './constants'
+import { socketFinalizationRegistry } from './internals'
+
+type RawIncomingPackets = [ RawIncomingPacket, ...RawIncomingPacket[] ]
+
+class Deferred {
+  #resolve!: (value: RawIncomingPackets) => void
+  #reject!: (reason: Error) => void
+  #packets: RawIncomingPacket[] = []
+
+  readonly promise: Promise<RawIncomingPackets>
+  readonly opcode: OPCODE
+
+  constructor(opcode: OPCODE) {
+    this.opcode = opcode
+
+    this.promise = new Promise((resolve, reject) => {
+      this.#resolve = resolve
+      this.#reject = reject
+    })
+  }
+
+  append(packet: RawIncomingPacket): void {
+    this.#packets.push(packet)
+  }
+
+  resolve(packet: RawIncomingPacket): void {
+    this.#packets.push(packet)
+    this.#resolve(this.#packets as RawIncomingPackets)
+  }
+
+  reject(error: Error): void {
+    this.#reject(error)
+  }
+}
+
+export interface ConnectionOptions {
+  host: string,
+  port?: number,
+  timeout?: number,
+}
+
+export class Connection {
+  readonly #decoder = new Decoder((packet) => this.#receive(packet))
+  readonly #encoder = new Encoder()
+  readonly #buffer = Buffer.allocUnsafeSlow(BUFFERS.BUFFER_SIZE)
+  readonly #defers = new Map<number, Deferred>()
+  readonly #factory: typeof net.connect
+
+  #socket?: Promise<Socket>
+  #sequence = 0
+
+  readonly #timeout: number
+  readonly #host: string
+  readonly #port: number
+
+  constructor(options: ConnectionOptions)
+  constructor(options: ConnectionOptions & { factory?: typeof net.connect }) {
+    assert(options, 'No options specified')
+
+    const {
+      host,
+      port = 11211,
+      timeout = 1000,
+      factory = net.connect,
+    } = options
+    this.#factory = factory
+
+    assert(host, 'No host name specified')
+    assert(port > 0 && port < 65536 && (Math.floor(port) == port), `Invalid port ${port}`)
+
+    this.#timeout = timeout
+    this.#host = host
+    this.#port = port
+  }
+
+  /* ======================================================================== */
+
+  get connected(): boolean {
+    return !! this.#socket
+  }
+
+  get host(): string {
+    return this.#host
+  }
+
+  get port(): number {
+    return this.#port
+  }
+
+  get timeout(): number {
+    return this.#timeout
+  }
+
+  /* ======================================================================== */
+
+  #connect(): Promise<Socket> {
+    return this.#socket || (this.#socket = new Promise((resolve, reject) => {
+      const socket: Socket = this.#factory({
+        host: this.#host,
+        port: this.#port,
+        timeout: this.#timeout,
+        onread: {
+          buffer: this.#buffer,
+          callback: (bytes: number, buffer: Buffer): boolean => {
+            this.#decoder.append(buffer, 0, bytes)
+            return true
+          },
+        },
+      })
+
+      socket.on('timeout', () => socket.destroy(new Error('Timeout')))
+      socket.on('error', reject)
+
+      socket.on('close', () => {
+        socketFinalizationRegistry.unregister(this)
+        this.#socket = undefined
+      })
+
+      socket.on('connect', () => {
+        socketFinalizationRegistry.register(this, socket, this)
+
+        socket.off('error', reject)
+        socket.on('error', (error) => {
+          for (const deferred of this.#defers.values()) {
+            process.nextTick(() => deferred.reject(error))
+          }
+          this.#defers.clear()
+          this.#socket = undefined
+        })
+
+        socket.unref()
+        resolve(socket)
+      })
+    }))
+  }
+
+  #receive(packet: RawIncomingPacket): void {
+    const deferred = this.#defers.get(packet.sequence)
+    if (deferred) {
+      if (deferred.opcode === packet.opcode) {
+        if ((packet.opcode === OPCODE.STAT) && (packet.key.length !== 0)) {
+          return deferred.append(packet)
+        }
+        return deferred.resolve(packet)
+      } else {
+        const sent = `0x${deferred.opcode.toString(16).padStart(2, '0')}`
+        const received = `0x${packet.opcode.toString(16).padStart(2, '0')}`
+        return deferred.reject(new Error(`Opcode mismatch (sent=${sent}, received=${received})`))
+      }
+    }
+  }
+
+  async send(packet: RawOutgoingPacket): Promise<RawIncomingPackets> {
+    const sequence = ++ this.#sequence
+    const buffer = this.#encoder.encode(packet, sequence)
+    const deferred = new Deferred(packet.opcode)
+
+    this.#defers.set(sequence, deferred)
+
+    const socket = await this.#connect()
+    socket.write(buffer, (error) => {
+      buffer.recycle()
+      if (error) return deferred.reject(error)
+    })
+
+    const timeout = setTimeout(() => deferred.reject(new Error('No response')), this.#timeout)
+
+    return deferred.promise.finally(() => {
+      clearTimeout(timeout)
+      this.#defers.delete(sequence)
+    })
+  }
+
+  async destroy(): Promise<boolean> {
+    const socket = await this.#socket
+    if (! socket) return false
+
+    return new Promise<boolean>((resolve, reject) => {
+      socket
+          .once('error', reject)
+          .once('close', resolve)
+          .destroy()
+    })
+  }
+}