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

    Fields

    No fields configured for Task.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions