@teammy/server 0.0.3 → 0.0.4

package/node_modules/find-my-way/lib/constrainer.js

@@ -0,0 +1,177 @@
+'use strict'
+
+const acceptVersionStrategy = require('./strategies/accept-version')
+const acceptHostStrategy = require('./strategies/accept-host')
+const assert = require('node:assert')
+
+class Constrainer {
+  constructor (customStrategies) {
+    this.strategies = {
+      version: acceptVersionStrategy,
+      host: acceptHostStrategy
+    }
+
+    this.strategiesInUse = new Set()
+    this.asyncStrategiesInUse = new Set()
+
+    // validate and optimize prototypes of given custom strategies
+    if (customStrategies) {
+      for (const strategy of Object.values(customStrategies)) {
+        this.addConstraintStrategy(strategy)
+      }
+    }
+  }
+
+  isStrategyUsed (strategyName) {
+    return this.strategiesInUse.has(strategyName) ||
+      this.asyncStrategiesInUse.has(strategyName)
+  }
+
+  hasConstraintStrategy (strategyName) {
+    if (!Object.hasOwn(this.strategies, strategyName)) return false
+    const customConstraintStrategy = this.strategies[strategyName]
+    if (customConstraintStrategy !== undefined) {
+      return customConstraintStrategy.isCustom ||
+        this.isStrategyUsed(strategyName)
+    }
+    return false
+  }
+
+  addConstraintStrategy (strategy) {
+    assert(typeof strategy.name === 'string' && strategy.name !== '', 'strategy.name is required.')
+    assert(strategy.storage && typeof strategy.storage === 'function', 'strategy.storage function is required.')
+    assert(strategy.deriveConstraint && typeof strategy.deriveConstraint === 'function', 'strategy.deriveConstraint function is required.')
+
+    if (Object.hasOwn(this.strategies, strategy.name) && this.strategies[strategy.name].isCustom) {
+      throw new Error(`There already exists a custom constraint with the name ${strategy.name}.`)
+    }
+
+    if (this.isStrategyUsed(strategy.name)) {
+      throw new Error(`There already exists a route with ${strategy.name} constraint.`)
+    }
+
+    strategy.isCustom = true
+    strategy.isAsync = strategy.deriveConstraint.length === 3
+    this.strategies[strategy.name] = strategy
+
+    if (strategy.mustMatchWhenDerived) {
+      this.noteUsage({ [strategy.name]: strategy })
+    }
+  }
+
+  deriveConstraints (req, ctx, done) {
+    const constraints = this.deriveSyncConstraints(req, ctx)
+
+    if (done === undefined) {
+      return constraints
+    }
+
+    this.deriveAsyncConstraints(constraints, req, ctx, done)
+  }
+
+  deriveSyncConstraints (req, ctx) {
+    return undefined
+  }
+
+  // When new constraints start getting used, we need to rebuild the deriver to derive them. Do so if we see novel constraints used.
+  noteUsage (constraints) {
+    if (constraints) {
+      const beforeSize = this.strategiesInUse.size
+      for (const key in constraints) {
+        if (!Object.hasOwn(constraints, key) || !Object.hasOwn(this.strategies, key)) continue
+        const strategy = this.strategies[key]
+        if (strategy.isAsync) {
+          this.asyncStrategiesInUse.add(key)
+        } else {
+          this.strategiesInUse.add(key)
+        }
+      }
+      if (beforeSize !== this.strategiesInUse.size) {
+        this._buildDeriveConstraints()
+      }
+    }
+  }
+
+  newStoreForConstraint (constraint) {
+    if (!Object.hasOwn(this.strategies, constraint) || !this.strategies[constraint]) {
+      throw new Error(`No strategy registered for constraint key ${constraint}`)
+    }
+    return this.strategies[constraint].storage()
+  }
+
+  validateConstraints (constraints) {
+    for (const key in constraints) {
+      if (!Object.hasOwn(constraints, key)) continue
+      const value = constraints[key]
+      if (typeof value === 'undefined') {
+        throw new Error('Can\'t pass an undefined constraint value, must pass null or no key at all')
+      }
+      const strategy = Object.hasOwn(this.strategies, key) ? this.strategies[key] : undefined
+      if (!strategy) {
+        throw new Error(`No strategy registered for constraint key ${key}`)
+      }
+      if (strategy.validate) {
+        strategy.validate(value)
+      }
+    }
+  }
+
+  deriveAsyncConstraints (constraints, req, ctx, done) {
+    let asyncConstraintsCount = this.asyncStrategiesInUse.size
+
+    if (asyncConstraintsCount === 0) {
+      done(null, constraints)
+      return
+    }
+
+    let errored = false
+    constraints = constraints || {}
+    for (const key of this.asyncStrategiesInUse) {
+      const strategy = this.strategies[key]
+      strategy.deriveConstraint(req, ctx, (err, constraintValue) => {
+        if (errored) return
+
+        if (err !== null) {
+          errored = true
+          done(err)
+          return
+        }
+
+        constraints[key] = constraintValue
+
+        if (--asyncConstraintsCount === 0) {
+          done(null, constraints)
+        }
+      })
+    }
+  }
+
+  // Optimization: build a fast function for deriving the constraints for all the strategies at once. We inline the definitions of the version constraint and the host constraint for performance.
+  // If no constraining strategies are in use (no routes constrain on host, or version, or any custom strategies) then we don't need to derive constraints for each route match, so don't do anything special, and just return undefined
+  // This allows us to not allocate an object to hold constraint values if no constraints are defined.
+  _buildDeriveConstraints () {
+    if (this.strategiesInUse.size === 0) return
+
+    const lines = ["'use strict'", 'return {']
+
+    for (const key of this.strategiesInUse) {
+      const strategy = this.strategies[key]
+      // Optimization: inline the derivation for the common built in constraints
+      if (!strategy.isCustom) {
+        if (key === 'version') {
+          lines.push('   version: req.headers[\'accept-version\'],')
+        } else {
+          lines.push('   host: req.headers.host || req.headers[\':authority\'],')
+        }
+      } else {
+        lines.push(`  ${strategy.name}: this.strategies.${key}.deriveConstraint(req, ctx),`)
+      }
+    }
+
+    lines.push('}')
+
+    this.deriveSyncConstraints = new Function('req', 'ctx', lines.join('\n')).bind(this) // eslint-disable-line
+  }
+}
+
+module.exports = Constrainer

package/node_modules/find-my-way/lib/handler-storage.js

@@ -0,0 +1,179 @@
+'use strict'
+
+const { NullObject } = require('./null-object')
+const httpMethodStrategy = require('./strategies/http-method')
+
+class HandlerStorage {
+  constructor () {
+    this.unconstrainedHandler = null // optimized reference to the handler that will match most of the time
+    this.constraints = []
+    this.handlers = [] // unoptimized list of handler objects for which the fast matcher function will be compiled
+    this.constrainedHandlerStores = null
+  }
+
+  // This is the hot path for node handler finding -- change with care!
+  getMatchingHandler (derivedConstraints) {
+    if (derivedConstraints === undefined) {
+      return this.unconstrainedHandler
+    }
+    return this._getHandlerMatchingConstraints(derivedConstraints)
+  }
+
+  addHandler (constrainer, route) {
+    const params = route.params
+    const constraints = route.opts.constraints || {}
+
+    const handlerObject = {
+      params,
+      constraints,
+      handler: route.handler,
+      store: route.store || null,
+      _createParamsObject: this._compileCreateParamsObject(params)
+    }
+
+    const constraintsNames = Object.keys(constraints)
+    if (constraintsNames.length === 0) {
+      this.unconstrainedHandler = handlerObject
+    }
+
+    for (const constraint of constraintsNames) {
+      if (!this.constraints.includes(constraint)) {
+        if (constraint === 'version') {
+          // always check the version constraint first as it is the most selective
+          this.constraints.unshift(constraint)
+        } else {
+          this.constraints.push(constraint)
+        }
+      }
+    }
+
+    const isMergedTree = constraintsNames.includes(httpMethodStrategy.name)
+    if (!isMergedTree && this.handlers.length >= 31) {
+      throw new Error('find-my-way supports a maximum of 31 route handlers per node when there are constraints, limit reached')
+    }
+
+    this.handlers.push(handlerObject)
+    // Sort the most constrained handlers to the front of the list of handlers so they are tested first.
+    this.handlers.sort((a, b) => Object.keys(a.constraints).length - Object.keys(b.constraints).length)
+
+    if (!isMergedTree) {
+      this._compileGetHandlerMatchingConstraints(constrainer, constraints)
+    }
+  }
+
+  _compileCreateParamsObject (params) {
+    const fnBody = ["'use strict'"]
+
+    // Parameter values arrive by position: the first four as arguments and
+    // any further ones in the extraParams array. This mirrors how the
+    // router's find() collects them without allocating an array.
+    fnBody.push('const fn = function _createParamsObject (param0, param1, param2, param3, extraParams) {')
+
+    fnBody.push('const params = new NullObject()')
+    for (let i = 0; i < params.length; i++) {
+      const value = i < 4 ? `param${i}` : `extraParams[${i - 4}]`
+      fnBody.push(`params[${JSON.stringify(params[i])}] = ${value}`)
+    }
+    fnBody.push('return params')
+    fnBody.push('}')
+
+    fnBody.push('return fn')
+
+    return new Function('NullObject', fnBody.join('\n'))(NullObject)  // eslint-disable-line
+  }
+
+  _getHandlerMatchingConstraints () {
+    return null
+  }
+
+  // Builds a store object that maps from constraint values to a bitmap of handler indexes which pass the constraint for a value
+  // So for a host constraint, this might look like { "fastify.io": 0b0010, "google.ca": 0b0101 }, meaning the 3rd handler is constrainted to fastify.io, and the 2nd and 4th handlers are constrained to google.ca.
+  // The store's implementation comes from the strategies provided to the Router.
+  _buildConstraintStore (store, constraint) {
+    for (let i = 0; i < this.handlers.length; i++) {
+      const handler = this.handlers[i]
+      const constraintValue = handler.constraints[constraint]
+      if (constraintValue !== undefined) {
+        let indexes = store.get(constraintValue) || 0
+        indexes |= 1 << i // set the i-th bit for the mask because this handler is constrained by this value https://stackoverflow.com/questions/1436438/how-do-you-set-clear-and-toggle-a-single-bit-in-javascrip
+        store.set(constraintValue, indexes)
+      }
+    }
+  }
+
+  // Builds a bitmask for a given constraint that has a bit for each handler index that is 0 when that handler *is* constrained and 1 when the handler *isnt* constrainted. This is opposite to what might be obvious, but is just for convienience when doing the bitwise operations.
+  _constrainedIndexBitmask (constraint) {
+    let mask = 0
+    for (let i = 0; i < this.handlers.length; i++) {
+      const handler = this.handlers[i]
+      const constraintValue = handler.constraints[constraint]
+      if (constraintValue !== undefined) {
+        mask |= 1 << i
+      }
+    }
+    return ~mask
+  }
+
+  // Compile a fast function to match the handlers for this node
+  // The function implements a general case multi-constraint matching algorithm.
+  // The general idea is this: we have a bunch of handlers, each with a potentially different set of constraints, and sometimes none at all. We're given a list of constraint values and we have to use the constraint-value-comparison strategies to see which handlers match the constraint values passed in.
+  // We do this by asking each constraint store which handler indexes match the given constraint value for each store. Trickily, the handlers that a store says match are the handlers constrained by that store, but handlers that aren't constrained at all by that store could still match just fine. So, each constraint store can only describe matches for it, and it won't have any bearing on the handlers it doesn't care about. For this reason, we have to ask each stores which handlers match and track which have been matched (or not cared about) by all of them.
+  // We use bitmaps to represent these lists of matches so we can use bitwise operations to implement this efficiently. Bitmaps are cheap to allocate, let us implement this masking behaviour in one CPU instruction, and are quite compact in memory. We start with a bitmap set to all 1s representing every handler that is a match candidate, and then for each constraint, see which handlers match using the store, and then mask the result by the mask of handlers that that store applies to, and bitwise AND with the candidate list. Phew.
+  // We consider all this compiling function complexity to be worth it, because the naive implementation that just loops over the handlers asking which stores match is quite a bit slower.
+  _compileGetHandlerMatchingConstraints (constrainer) {
+    this.constrainedHandlerStores = {}
+
+    for (const constraint of this.constraints) {
+      const store = constrainer.newStoreForConstraint(constraint)
+      this.constrainedHandlerStores[constraint] = store
+
+      this._buildConstraintStore(store, constraint)
+    }
+
+    const lines = ["'use strict'"]
+    lines.push(`
+    let candidates = ${(1 << this.handlers.length) - 1}
+    let mask, matches, value
+    `)
+    for (const constraint of this.constraints) {
+      // Setup the mask for indexes this constraint applies to. The mask bits are set to 1 for each position if the constraint applies.
+      lines.push(`
+      mask = ${this._constrainedIndexBitmask(constraint)}
+      value = derivedConstraints.${constraint}
+      `)
+
+      // If there's no constraint value, none of the handlers constrained by this constraint can match. Remove them from the candidates.
+      // If there is a constraint value, get the matching indexes bitmap from the store, and mask it down to only the indexes this constraint applies to, and then bitwise and with the candidates list to leave only matching candidates left.
+      const strategy = constrainer.strategies[constraint]
+      const matchMask = strategy.mustMatchWhenDerived ? 'matches' : '(matches | mask)'
+
+      lines.push(`
+      if (value === undefined) {
+        candidates &= mask
+      } else {
+        matches = this.constrainedHandlerStores.${constraint}.get(value) || 0
+        candidates &= ${matchMask}
+      }
+      if (candidates === 0) return null;
+      `)
+    }
+
+    // There are some constraints that can be derived and marked as "must match", where if they are derived, they only match routes that actually have a constraint on the value, like the SemVer version constraint.
+    // An example: a request comes in for version 1.x, and this node has a handler that matches the path, but there's no version constraint. For SemVer, the find-my-way semantics do not match this handler to that request.
+    // This function is used by Nodes with handlers to match when they don't have any constrained routes to exclude request that do have must match derived constraints present.
+    for (const constraint in constrainer.strategies) {
+      if (!Object.hasOwn(constrainer.strategies, constraint)) continue
+      const strategy = constrainer.strategies[constraint]
+      if (strategy.mustMatchWhenDerived && !this.constraints.includes(constraint)) {
+        lines.push(`if (derivedConstraints.${constraint} !== undefined) return null`)
+      }
+    }
+
+    // Return the highest set bit index in the candidates bitmask.
+    lines.push('return this.handlers[31 - Math.clz32(candidates)]')
+
+    this._getHandlerMatchingConstraints = new Function('derivedConstraints', lines.join('\n')) // eslint-disable-line
+  }
+}
+
+module.exports = HandlerStorage

package/node_modules/find-my-way/lib/http-methods.js

@@ -0,0 +1,13 @@
+'use strict'
+
+// defined by Node.js http module, a snapshot from Node.js 22.9.0
+const httpMethods = [
+  'ACL', 'BIND', 'CHECKOUT', 'CONNECT', 'COPY', 'DELETE',
+  'GET', 'HEAD', 'LINK', 'LOCK', 'M-SEARCH', 'MERGE',
+  'MKACTIVITY', 'MKCALENDAR', 'MKCOL', 'MOVE', 'NOTIFY', 'OPTIONS',
+  'PATCH', 'POST', 'PROPFIND', 'PROPPATCH', 'PURGE', 'PUT', 'QUERY',
+  'REBIND', 'REPORT', 'SEARCH', 'SOURCE', 'SUBSCRIBE', 'TRACE',
+  'UNBIND', 'UNLINK', 'UNLOCK', 'UNSUBSCRIBE'
+]
+
+module.exports = httpMethods

package/node_modules/find-my-way/lib/node.js

@@ -0,0 +1,250 @@
+'use strict'
+
+const HandlerStorage = require('./handler-storage')
+
+const NODE_TYPES = {
+  STATIC: 0,
+  PARAMETRIC: 1,
+  WILDCARD: 2
+}
+
+// Prefixes at least this long are matched with a native String#indexOf, which
+// runs in roughly constant time, instead of the compiled chain of charCodeAt
+// comparisons whose cost grows with every char.
+const LONG_PREFIX_MIN_LENGTH = 16
+
+function matchSingleCharPrefix () {
+  return true
+}
+
+function compilePrefixMatch (prefix) {
+  if (prefix.length === 1) {
+    return matchSingleCharPrefix
+  }
+
+  if (prefix.length >= LONG_PREFIX_MIN_LENGTH) {
+    return function matchLongPrefix (path, i) {
+      return path.indexOf(prefix, i) === i
+    }
+  }
+
+  const lines = []
+  for (let i = 1; i < prefix.length; i++) {
+    const charCode = prefix.charCodeAt(i)
+    lines.push(`path.charCodeAt(i + ${i}) === ${charCode}`)
+  }
+  return new Function('path', 'i', `'use strict'\nreturn ${lines.join(' && ')}`) // eslint-disable-line
+}
+
+// Every node kind is an instance of this one class so that all nodes share a
+// single hidden class. The router's lookup loop alternates between static,
+// parametric and wildcard nodes, and with one shape every property access in
+// that loop stays monomorphic. Fields that only apply to some kinds are set to
+// their neutral value on the others: the lookup loop can then read
+// staticChildren, parametricChildren and wildcardChild from any node without
+// checking its kind first.
+class Node {
+  constructor (kind, prefix, regex, staticSuffix, nodePath) {
+    this.kind = kind
+    this.prefix = prefix
+    this.isLeafNode = false
+    this.routes = null
+    this.handlerStorage = null
+
+    // Static children are stored in parallel arrays keyed by the charCode of
+    // the child's first char. A linear scan over integers is faster than a
+    // dictionary lookup by single-char string on the hot path.
+    this.staticChildrenCharCodes = []
+    this.staticChildrenNodes = []
+
+    // static node only
+    this.parametricChildren = []
+    this.wildcardChild = null
+    this.matchPrefix = kind === NODE_TYPES.STATIC ? compilePrefixMatch(prefix) : null
+
+    // parametric node only
+    this.isRegex = regex != null
+    this.regex = regex || null
+    this.staticSuffix = staticSuffix || null
+    this.nodePaths = kind === NODE_TYPES.PARAMETRIC ? new Set([nodePath]) : null
+  }
+
+  addRoute (route, constrainer) {
+    if (this.routes === null) {
+      this.routes = []
+    }
+    if (this.handlerStorage === null) {
+      this.handlerStorage = new HandlerStorage()
+    }
+    this.isLeafNode = true
+    this.routes.push(route)
+    this.handlerStorage.addHandler(constrainer, route)
+  }
+
+  setStaticChild (label, node) {
+    const charCode = label.charCodeAt(0)
+    const index = this.staticChildrenCharCodes.indexOf(charCode)
+    if (index === -1) {
+      this.staticChildrenCharCodes.push(charCode)
+      this.staticChildrenNodes.push(node)
+    } else {
+      this.staticChildrenNodes[index] = node
+    }
+  }
+
+  findStaticMatchingChild (path, pathIndex) {
+    const charCode = path.charCodeAt(pathIndex)
+    const charCodes = this.staticChildrenCharCodes
+    for (let i = 0; i < charCodes.length; i++) {
+      if (charCodes[i] === charCode) {
+        const staticChild = this.staticChildrenNodes[i]
+        if (staticChild.matchPrefix(path, pathIndex)) {
+          return staticChild
+        }
+        return null
+      }
+    }
+    return null
+  }
+
+  getStaticChild (path, pathIndex = 0) {
+    if (path.length === pathIndex) {
+      return this
+    }
+
+    const staticChild = this.findStaticMatchingChild(path, pathIndex)
+    if (staticChild) {
+      return staticChild.getStaticChild(path, pathIndex + staticChild.prefix.length)
+    }
+
+    return null
+  }
+
+  createStaticChild (path) {
+    if (path.length === 0) {
+      return this
+    }
+
+    const childIndex = this.staticChildrenCharCodes.indexOf(path.charCodeAt(0))
+    let staticChild = childIndex === -1 ? undefined : this.staticChildrenNodes[childIndex]
+    if (staticChild) {
+      let i = 1
+      for (; i < staticChild.prefix.length; i++) {
+        if (path.charCodeAt(i) !== staticChild.prefix.charCodeAt(i)) {
+          staticChild = staticChild.split(this, i)
+          break
+        }
+      }
+      return staticChild.createStaticChild(path.slice(i))
+    }
+
+    const node = createStaticNode(path)
+    this.setStaticChild(path.charAt(0), node)
+    return node
+  }
+
+  getParametricChild (regex) {
+    const regexpSource = regex && regex.source
+
+    const parametricChild = this.parametricChildren.find(child => {
+      const childRegexSource = child.regex && child.regex.source
+      return childRegexSource === regexpSource
+    })
+
+    if (parametricChild) {
+      return parametricChild
+    }
+
+    return null
+  }
+
+  createParametricChild (regex, staticSuffix, nodePath) {
+    let parametricChild = this.getParametricChild(regex)
+    if (parametricChild) {
+      parametricChild.nodePaths.add(nodePath)
+      return parametricChild
+    }
+
+    parametricChild = createParametricNode(regex, staticSuffix, nodePath)
+    this.parametricChildren.push(parametricChild)
+    this.parametricChildren.sort((child1, child2) => {
+      if (!child1.isRegex) return 1
+      if (!child2.isRegex) return -1
+
+      if (child1.staticSuffix === null) return 1
+      if (child2.staticSuffix === null) return -1
+
+      if (child2.staticSuffix.endsWith(child1.staticSuffix)) return 1
+      if (child1.staticSuffix.endsWith(child2.staticSuffix)) return -1
+
+      return 0
+    })
+
+    return parametricChild
+  }
+
+  getWildcardChild () {
+    return this.wildcardChild
+  }
+
+  createWildcardChild () {
+    this.wildcardChild = this.getWildcardChild() || createWildcardNode()
+    return this.wildcardChild
+  }
+
+  // Returns the next node to visit for the path at pathIndex, preferring a
+  // static child, then the first parametric child, then the wildcard. Every
+  // sibling that is skipped over is pushed on nodeStack as a flat triple
+  // (node, pathIndex, paramsCount) so lookup can backtrack to it later.
+  getNextNode (path, pathIndex, nodeStack, paramsCount) {
+    let node = this.findStaticMatchingChild(path, pathIndex)
+    let parametricBrotherNodeIndex = 0
+
+    if (node === null) {
+      if (this.parametricChildren.length === 0) {
+        return this.wildcardChild
+      }
+
+      node = this.parametricChildren[0]
+      parametricBrotherNodeIndex = 1
+    }
+
+    if (this.wildcardChild !== null) {
+      nodeStack.push(this.wildcardChild, pathIndex, paramsCount)
+    }
+
+    for (let i = this.parametricChildren.length - 1; i >= parametricBrotherNodeIndex; i--) {
+      nodeStack.push(this.parametricChildren[i], pathIndex, paramsCount)
+    }
+
+    return node
+  }
+
+  split (parentNode, length) {
+    const parentPrefix = this.prefix.slice(0, length)
+    const childPrefix = this.prefix.slice(length)
+
+    this.prefix = childPrefix
+    this.matchPrefix = compilePrefixMatch(childPrefix)
+
+    const staticNode = createStaticNode(parentPrefix)
+    staticNode.setStaticChild(childPrefix.charAt(0), this)
+    parentNode.setStaticChild(parentPrefix.charAt(0), staticNode)
+
+    return staticNode
+  }
+}
+
+function createStaticNode (prefix) {
+  return new Node(NODE_TYPES.STATIC, prefix, null, null, null)
+}
+
+function createParametricNode (regex, staticSuffix, nodePath) {
+  return new Node(NODE_TYPES.PARAMETRIC, '', regex, staticSuffix, nodePath)
+}
+
+function createWildcardNode () {
+  return new Node(NODE_TYPES.WILDCARD, '', null, null, null)
+}
+
+module.exports = { Node, createStaticNode, createParametricNode, createWildcardNode, NODE_TYPES }

package/node_modules/find-my-way/lib/null-object.js

@@ -0,0 +1,8 @@
+'use strict'
+
+const NullObject = function () {}
+NullObject.prototype = Object.create(null)
+
+module.exports = {
+  NullObject
+}