spring-boot-starter-actor icon indicating copy to clipboard operation
spring-boot-starter-actor copied to clipboard

Add Pekko Receptionist support for dynamic actor discovery

Open Copilot opened this issue 2 months ago • 0 comments

Description

Adds support for Pekko's Receptionist, enabling dynamic actor discovery by service type rather than requiring exact actor names. This addresses the gap where actors must currently be discovered via getOrSpawn("exact-name"), preventing patterns like worker pools and dynamic service discovery.

Changes Made

Core API (core/src/main/java/io/github/seonwkim/core/receptionist/)

  • ServiceKey<T> - Type-safe keys for service registration
  • Listing<T> - Immutable snapshot of registered actors
  • SpringReceptionistService - Main API: register(), find(), subscribe()
  • SpringActorSystem.receptionist() - Accessor method for service

API Example

// Define service key
ServiceKey<WorkerActor.Command> workerKey = 
    ServiceKey.create(WorkerActor.Command.class, "worker-pool");

// Register actors
receptionist.register(workerKey, workerRef);

// Find all registered actors
receptionist.find(workerKey).thenAccept(listing -> {
    Set<SpringActorRef<Command>> workers = listing.getServiceInstances();
    // Distribute work across workers
});

// Subscribe to availability changes
receptionist.subscribe(workerKey, listing -> {
    log.info("Pool size: {}", listing.size());
});

Tests

  • 11 comprehensive tests covering registration, discovery, subscriptions, load balancing
  • All 159 tests passing (11 new + 148 existing, zero regressions)

Example Application (example/receptionist/)

  • Worker pool with dynamic scaling and round-robin load balancing
  • REST API demonstrating registration, discovery, and subscription patterns
  • Full documentation with usage examples

Additional Context

Enables patterns:

  • Worker pools (multiple actors under same key)
  • Service discovery without hard-coded names
  • Load balancing with automatic failover
  • Availability monitoring via subscriptions

Works in both local and cluster modes. Zero breaking changes.

Aligns with roadmap item 5.4 (Cluster Pub-Sub) which references receptionist as foundation.

Original prompt

I would like you to investigate whether we should add support for pekko's Receptionist feature for better actor discovery. If you think it's needed, write a MVP with DX in mind.


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot avatar Nov 13 '25 09:11 Copilot