Skip to content

Introduce explicit endpoint replacement flow for existing host_id #923

Description

@dkropachev

Parent epic: #921

Problem

The driver currently mutates Host.endpoint during topology refresh when a node keeps the same host_id but changes address. Direct mutation makes it hard to keep metadata indexes, session pools, load-balancing policies, client routes, and async connection work consistent.

Before Host.endpoint can be frozen, endpoint movement needs one explicit internal flow that owns the full transition.

Desired behavior

A same-host_id, different-endpoint observation should go through a single endpoint replacement/update path that:

  • validates that the host_id is unchanged;
  • updates metadata endpoint indexes atomically from the driver's perspective;
  • retires or renews affected session pools;
  • notifies load-balancing policies with clear remove/add or update semantics;
  • invalidates/fences stale async pool and connection work;
  • keeps runtime health behavior well-defined during the transition;
  • preserves compatibility for public address lookup APIs where possible.

Scope

  • Define the internal API for endpoint replacement.
  • Route control connection topology refresh through that API.
  • Ensure metadata, sessions, policies, and route state observe a coherent transition.
  • Decide whether the existing Host object is retained with controlled internal update or replaced by a new Host object during the transition.
  • Document the chosen semantics in code/tests.

Acceptance criteria

  • There is one internal path for same-host_id endpoint movement.
  • Callers no longer assign host.endpoint directly during topology refresh.
  • Metadata endpoint indexes cannot retain stale endpoint mappings after replacement.
  • Sessions do not keep using pools opened for the previous endpoint after replacement.
  • Tests cover endpoint movement with preserved host_id.

Part of #921. Depends on #922 and #867. Related to #857, #858, #859, and #860.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions