Class GroupMembership

java.lang.Object
ai.badmonkey.agentspaces.peering.membership.GroupMembership
All Implemented Interfaces:
PeerSampler
public final class GroupMembership extends Object implements PeerSampler
Leased membership for one group (spec §5.2): the membership view is fed by leased PeerAdvertisements arriving over gossip and by direct liveness contact, and a member that neither gossips nor answers within its TTL is dropped without ceremony (spec P2). A SWIM-style probe cycle runs on tick(GroupMembership.Prober): ping a random member, and on timeout ask indirectPeers others to probe the target before dropping it.

Deterministic by construction: time comes from the injected clock, randomness from the injected Random, and probing advances only on tick.

  • Constructor Details

    • GroupMembership

      public GroupMembership(PeerId self, InstantSource clock, Random random, GroupMembership.Config config)
      Creates the membership view.
      Parameters:
      self - the local peer (never a member of its own view)
      clock - the time source
      random - the randomness source (seed it in tests)
      config - membership tuning

  • Method Details

    • refuse

      public void refuse(Predicate<PeerId> refused)
      Sets the peers this view must never admit, consulted on every advertisement: the group's revocations (ASF-047). Late-bound because the view is built before the group's revocation registry.
      Parameters:
      refused - the peers to refuse

    • onPeerAdvertisement

      public void onPeerAdvertisement(PeerAdvertisement ad)
      Feeds a verified PeerAdvertisement into the view, refreshing endpoints and liveness.
      Parameters:
      ad - the advertisement (already signature-verified by the caller)

    • evict

      public void evict(PeerId peer)
      Removes a peer from the view immediately (a revocation's enforcement, or any other authoritative eject). Idempotent.
      Parameters:
      peer - the peer to evict

    • recordHeard

      public void recordHeard(PeerId peer)
      Records direct contact from a peer (any verified frame counts as liveness).
      Parameters:
      peer - the peer heard from

    • onAck

      public void onAck(long nonce, PeerId from)
      Handles an ACK correlated to an outstanding probe. The liveness credit always goes to the probe's own recorded target — never to any identity the wire supplies — and the ACK counts only when its authenticated sender is that target (a direct probe) or a relay this node actually asked (an indirect probe). A sprayed or forged ACK neither cancels the probe nor marks anyone alive (ASF-011).
      Parameters:
      nonce - the echoed nonce
      from - the frame's authenticated sender

    • tick

      public void tick(GroupMembership.Prober prober)
      Runs one membership round: expire silent members, escalate or drop timed-out probes, and probe one random member.
      Parameters:
      prober - the frame sender

    • member

      public Optional<GroupMembership.Member> member(PeerId peer)
      Looks up a member.
      Parameters:
      peer - the member id
      Returns:
      the member, when present in the view

    • allMembers

      public List<GroupMembership.Member> allMembers()
      Returns a snapshot of all current members.

    • withRole

      public List<PeerId> withRole(PeerAdvertisement.PeerRole role)
      Returns the members currently advertising a topology role.
      Parameters:
      role - the role
      Returns:
      members offering it

    • randomMembers

      public List<PeerId> randomMembers(int n)
      Description copied from interface: PeerSampler
      Returns up to n live members chosen uniformly at random, excluding the local peer.
      Specified by:
      randomMembers in interface PeerSampler
      Parameters:
      n - the maximum number of members to return
      Returns:
      the sampled members, possibly fewer than n