Replace existing HashRing nodes when primary keys match

[fubhy]

Summary

Adding a replacement node with an existing PrimaryKey updates at most its weight. Routing, iteration, JSON output, and shard assignment continue returning the old node value, including when the replacement has the same weight.

Important

This PR starts with focused failing reproduction tests. Add the implementation fix to this same branch; CI is expected to fail until that fix is included.

Re-adding an existing primary key retains the stale node

Module: HashRing
Audit ID: core-g-r-hashring-existing-key-retains-stale-node
Severity / confidence: medium / high

What happens

Adding a replacement node with an existing PrimaryKey updates at most its weight. Routing, iteration, JSON output, and shard assignment continue returning the old node value, including when the replacement has the same weight.

Why it happens

For an existing key, addMany assigns only entry[1], the weight, and never replaces entry[0], the node. The same-weight branch returns before any update, while all value-returning operations continue reading entry[0].

Expected behavior

add and addMany update an existing node keyed by PrimaryKey.value, and subsequent routing returns the currently registered node value.

Relevant implementation

These links and excerpts are pinned to audit base c9b56ab507f224426ee8388dc450da447ec4715f.

• packages/effect/src/HashRing.ts:118-165
• packages/effect/src/HashRing.ts:297-304
• packages/effect/src/HashRing.ts:317-377

View problematic code at packages/effect/src/HashRing.ts:118-165

/**
 * Adds new nodes to the ring. If a node already exists in the ring, it
 * will be updated. For example, you can use this to update the node's weight.
 *
 * **When to use**
 *
 * Use to register or update several nodes in a `HashRing` at the same weight.
 *
 * @category combinators
 * @since 3.19.0
 */
export const addMany: {
  <A extends PrimaryKey.PrimaryKey>(nodes: Iterable<A>, options?: {
    readonly weight?: number | undefined
  }): (self: HashRing<A>) => HashRing<A>
  <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, nodes: Iterable<A>, options?: {
    readonly weight?: number | undefined
  }): HashRing<A>
} = dual(
  (args) => isHashRing(args[0]),
  <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, nodes: Iterable<A>, options?: {
    readonly weight?: number | undefined
  }): HashRing<A> => {
    const weight = Math.max(options?.weight ?? 1, 0.1)
    const keys: Array<string> = []
    let toRemove: Set<string> | undefined
    for (const node of nodes) {
      const key = PrimaryKey.value(node)
      const entry = self.nodes.get(key)
      if (entry) {
        if (entry[1] === weight) continue
        toRemove ??= new Set()
        toRemove.add(key)
        self.totalWeightCache -= entry[1]
        self.totalWeightCache += weight
        entry[1] = weight
      } else {
        self.nodes.set(key, [node, weight])
        self.totalWeightCache += weight
      }
      keys.push(key)
    }
    if (toRemove) {
      self.ring = self.ring.filter(([, n]) => !toRemove.has(n))
    }
    addNodesToRing(self, keys, Math.round(weight * self.baseWeight))
    return self
  }

View exact lines on GitHub

View problematic code at packages/effect/src/HashRing.ts:297-304

export const get = <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, input: string): A | undefined => {
  if (self.ring.length === 0) {
    return undefined
  }
  const index = getIndexForInput(self, Hash.string(input))[0]
  const node = self.ring[index][1]!
  return self.nodes.get(node)![0]
}

View exact lines on GitHub

View problematic code at packages/effect/src/HashRing.ts:317-366

export const getShards = <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, count: number): Array<A> | undefined => {
  if (self.ring.length === 0) {
    return undefined
  }

  const shards = new Array<A>(count)

  // for tracking how many shards have been allocated to each node
  const allocations = new Map<string, number>()
  // for tracking which shards still need to be allocated
  const remaining = new Set<number>()
  // for tracking which nodes have reached the max allocation
  const exclude = new Set<string>()

  // First pass - allocate the closest nodes, skipping nodes that have reached
  // max
  const distances = new Array<[shard: number, node: string, distance: number]>(count)
  for (let shard = 0; shard < count; shard++) {
    const hash = (shardHashes[shard] ??= Hash.string(`shard-${shard}`))
    const [index, distance] = getIndexForInput(self, hash)
    const node = self.ring[index][1]!
    distances[shard] = [shard, node, distance]
    remaining.add(shard)
  }
  distances.sort((a, b) => a[2] - b[2])
  for (let i = 0; i < count; i++) {
    const [shard, node] = distances[i]
    if (exclude.has(node)) continue
    const [value, weight] = self.nodes.get(node)!
    shards[shard] = value
    remaining.delete(shard)
    const nodeCount = (allocations.get(node) ?? 0) + 1
    allocations.set(node, nodeCount)
    const maxPerNode = Math.max(1, Math.floor(count * (weight / self.totalWeightCache)))
    if (nodeCount >= maxPerNode) {
      exclude.add(node)
    }
  }

  // Second pass - allocate any remaining shards, skipping nodes that have
  // reached max
  let allAtMax = exclude.size === self.nodes.size
  remaining.forEach((shard) => {
    const index = getIndexForInput(self, shardHashes[shard], allAtMax ? undefined : exclude)[0]
    const node = self.ring[index][1]
    const [value, weight] = self.nodes.get(node)!
    shards[shard] = value

    if (allAtMax) return
    const nodeCount = (allocations.get(node) ?? 0) + 1

View exact lines on GitHub

Excerpt truncated. Open the complete packages/effect/src/HashRing.ts:317-377 range.

Reproduction

pnpm vitest run packages/effect/test/HashRing.test.ts

Observed failure: The intended failure was reproduced: the first node was returned instead of its replacement.

Implementation handoff

The initial reproduction tests on this branch are the regression specification for the implementation fix that should follow in this PR.

1. Start with the pinned implementation excerpts and the Why it happens analysis above.
2. Change the implementation so it satisfies the stated Expected behavior; do not weaken or remove the reproduction assertions.
3. Run the focused reproduction command(s) and confirm the observed failures become passing tests:

pnpm vitest run packages/effect/test/HashRing.test.ts

4. Run the affected package's existing tests, then the repository lint and type checks before requesting review.

Audit provenance

• Audit base: c9b56ab507f224426ee8388dc450da447ec4715f
• Reproduction base: c9b56ab507f224426ee8388dc450da447ec4715f
• Findings: core-g-r-hashring-existing-key-retains-stale-node
• Initial patch: focused reproduction tests; implementation fix pending

Closes EFF-341

[changeset-bot]

🦋 Changeset detected

Latest commit: a9d57b7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 30 packages

Name	Type
effect	Patch
@effect/opentelemetry	Patch
@effect/platform-browser	Patch
@effect/platform-bun	Patch
@effect/platform-deno	Patch
@effect/platform-node-shared	Patch
@effect/platform-node	Patch
@effect/vitest	Patch
@effect/ai-anthropic	Patch
@effect/ai-openai-compat	Patch
@effect/ai-openai	Patch
@effect/ai-openrouter	Patch
@effect/atom-react	Patch
@effect/atom-solid	Patch
@effect/atom-vue	Patch
@effect/sql-clickhouse	Patch
@effect/sql-d1	Patch
@effect/sql-libsql	Patch
@effect/sql-mssql	Patch
@effect/sql-mysql2	Patch
@effect/sql-pg	Patch
@effect/sql-pglite	Patch
@effect/sql-sqlite-bun	Patch
@effect/sql-sqlite-do	Patch
@effect/sql-sqlite-node	Patch
@effect/sql-sqlite-react-native	Patch
@effect/sql-sqlite-wasm	Patch
@effect/docgen	Patch
@effect/doctest	Patch
@effect/openapi-generator	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pullfrog]

✅ No new issues found.

Reviewed changes

• HashRing reproduction test — adds a single test case verifying that HashRing.add with a different node object sharing the same PrimaryKey.value updates the stored node; the test correctly fails, confirming the bug where addMany's if (entry[1] === weight) continue on packages/effect/src/HashRing.ts:148 skips the node reference update when the weight is unchanged.

The test reproduces the audit finding core-g-r-hashring-existing-key-retains-stale-node: after add(ring, first) then add(ring, updated) (both sharing primary key "node"), HashRing.get returns first instead of updated.

Note: the same stale-node issue also affects the different-weight path on packages/effect/src/HashRing.ts:153 — entry[1] = weight only updates the weight in the existing tuple, not the node reference at entry[0]. The fix will likely need to replace the entire entry on both code paths.

ℹ️ The test is intentionally failing (CI breakage expected). The author may want to consider it.fails to make the test expected-failure rather than a hard CI failure, at least until the fix lands — but mirroring the impact of a production bug by letting CI play it out as real failures is also a valid choice.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

The fix is a single line (entry[0] = node) that replaces the stale node reference when re-adding a value with the same PrimaryKey, plus a second test covering the weight-changing path. Both tests pass.

• Applied the HashRing node-replacement fix — added entry[0] = node in addMany before the same-weight early return, so both same-weight and different-weight replacement paths now update the stored node.
• Added weight-change regression test — verifies that HashRing.add with a different weight also replaces the node, not just the weight.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

[github-actions]

Bundle Size Analysis

Generated from PR build output; treat the content below as untrusted.

File Name	Current Size	Previous Size	Difference
basic.ts	7.06 KB	7.06 KB	0.00 KB (0.00%)
batching.ts	9.86 KB	9.86 KB	0.00 KB (0.00%)
brand.ts	6.34 KB	6.34 KB	0.00 KB (0.00%)
cache.ts	10.62 KB	10.62 KB	0.00 KB (0.00%)
config.ts	20.60 KB	20.60 KB	0.00 KB (0.00%)
differ.ts	20.20 KB	20.20 KB	0.00 KB (0.00%)
http-client.ts	21.49 KB	21.49 KB	0.00 KB (0.00%)
logger.ts	10.76 KB	10.76 KB	0.00 KB (0.00%)
metric.ts	8.99 KB	8.99 KB	0.00 KB (0.00%)
optic.ts	7.18 KB	7.18 KB	0.00 KB (0.00%)
pubsub.ts	14.90 KB	14.90 KB	0.00 KB (0.00%)
queue.ts	11.58 KB	11.58 KB	0.00 KB (0.00%)
schedule.ts	10.74 KB	10.74 KB	0.00 KB (0.00%)
schema-class.ts	19.14 KB	19.14 KB	0.00 KB (0.00%)
schema-fromJsonSchemaDocument.ts	28.96 KB	28.96 KB	0.00 KB (0.00%)
schema-representation-roundtrip.ts	25.29 KB	25.29 KB	0.00 KB (0.00%)
schema-string-transformation.ts	13.30 KB	13.30 KB	0.00 KB (0.00%)
schema-string.ts	10.94 KB	10.94 KB	0.00 KB (0.00%)
schema-template-literal.ts	15.17 KB	15.17 KB	0.00 KB (0.00%)
schema-toArbitraryLazy.ts	21.94 KB	21.94 KB	0.00 KB (0.00%)
schema-toCodeDocument.ts	24.34 KB	24.34 KB	0.00 KB (0.00%)
schema-toCodecJson.ts	19.18 KB	19.18 KB	0.00 KB (0.00%)
schema-toEquivalence.ts	19.01 KB	19.01 KB	0.00 KB (0.00%)
schema-toFormatter.ts	18.87 KB	18.87 KB	0.00 KB (0.00%)
schema-toJsonSchemaDocument.ts	22.60 KB	22.60 KB	0.00 KB (0.00%)
schema-toRepresentation.ts	19.52 KB	19.52 KB	0.00 KB (0.00%)
schema.ts	18.41 KB	18.41 KB	0.00 KB (0.00%)
stm.ts	12.54 KB	12.54 KB	0.00 KB (0.00%)
stream.ts	9.79 KB	9.79 KB	0.00 KB (0.00%)