Struct ServiceManager 

pub struct ServiceManager { /* private fields */ }

Service manager for multiple services

Implementations

impl ServiceManager

pub fn builder(runtime: Arc<dyn Runtime + Send + Sync>) -> ServiceManagerBuilder

Create a ServiceManagerBuilder for constructing a ServiceManager.

This is the preferred way to construct a ServiceManager since v0.2.0.

Example

let manager = ServiceManager::builder(runtime)
    .overlay_manager(om)
    .proxy_manager(proxy)
    .build();

pub fn new(runtime: Arc<dyn Runtime + Send + Sync>) -> Self

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Create a new service manager

pub fn with_overlay( runtime: Arc<dyn Runtime + Send + Sync>, overlay_manager: Arc<RwLock<OverlayManager>>, ) -> Self

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Create a service manager with overlay network support

pub fn with_full_config( runtime: Arc<dyn Runtime + Send + Sync>, overlay_manager: Arc<RwLock<OverlayManager>>, deployment_name: String, ) -> Self

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Create a fully-configured service manager with overlay and proxy support

pub fn health_states(&self) -> Arc<RwLock<HashMap<String, HealthState>>>

Get the health states map for external monitoring

pub async fn update_health_state(&self, service_name: &str, state: HealthState)

Update health state for a service

pub fn set_deployment_name(&mut self, name: String)

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Set the deployment name (used for generating hostnames)

pub fn set_stream_registry(&mut self, registry: Arc<StreamRegistry>)

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Set the stream registry for L4 proxy integration (TCP/UDP)

pub fn with_stream_registry(self, registry: Arc<StreamRegistry>) -> Self

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Builder pattern: add stream registry for L4 proxy integration

pub fn stream_registry(&self) -> Option<&Arc<StreamRegistry>>

Get the stream registry (if configured)

pub fn set_overlay_manager(&mut self, manager: Arc<RwLock<OverlayManager>>)

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Set the overlay manager for container networking

pub fn set_proxy_manager(&mut self, proxy: Arc<ProxyManager>)

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Set the proxy manager for health-aware load balancing

pub fn with_proxy_manager(self, proxy: Arc<ProxyManager>) -> Self

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Builder pattern: add proxy manager for health-aware load balancing

pub fn proxy_manager(&self) -> Option<&Arc<ProxyManager>>

Get the proxy manager (if configured)

pub fn set_dns_server(&mut self, dns: Arc<DnsServer>)

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Set the DNS server for service discovery

pub fn with_dns_server(self, dns: Arc<DnsServer>) -> Self

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Builder pattern: add DNS server for service discovery

pub fn dns_server(&self) -> Option<&Arc<DnsServer>>

Get the DNS server (if configured)

pub fn set_job_executor(&mut self, executor: Arc<JobExecutor>)

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Set the job executor for run-to-completion workloads

pub fn set_cron_scheduler(&mut self, scheduler: Arc<CronScheduler>)

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Set the cron scheduler for time-based job triggers

pub fn with_job_executor(self, executor: Arc<JobExecutor>) -> Self

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Builder pattern: add job executor

pub fn with_cron_scheduler(self, scheduler: Arc<CronScheduler>) -> Self

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Builder pattern: add cron scheduler

pub fn set_cluster(&mut self, cluster: Arc<dyn Cluster>)

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Set the cluster handle for cluster-aware scaling.

pub fn with_cluster(self, cluster: Arc<dyn Cluster>) -> Self

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Builder pattern: add a cluster handle for cluster-aware scaling.

pub fn cluster(&self) -> Option<&Arc<dyn Cluster>>

Get the cluster handle (if configured).

pub fn set_ingress(&mut self, enabled: bool)

Set whether THIS node holds the standing HTTP/HTTPS ingress (mirrors NodeConfig.ingress). Threaded onto each new ServiceInstance so its external service domains resolve to this node’s overlay IP when it is the funnel. Defaults to false.

pub fn ingress(&self) -> bool

Whether THIS node holds the standing HTTP/HTTPS ingress.

pub fn job_executor(&self) -> Option<&Arc<JobExecutor>>

Get the job executor (if configured)

pub fn cron_scheduler(&self) -> Option<&Arc<CronScheduler>>

Get the cron scheduler (if configured)

pub fn set_container_supervisor(&mut self, supervisor: Arc<ContainerSupervisor>)

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Set the container supervisor for crash/panic policy enforcement

pub fn with_container_supervisor( self, supervisor: Arc<ContainerSupervisor>, ) -> Self

👎Deprecated since 0.2.0:

use ServiceManager::builder() instead

Builder pattern: add container supervisor

pub fn container_supervisor(&self) -> Option<&Arc<ContainerSupervisor>>

Get the container supervisor (if configured)

pub fn start_container_supervisor(&self) -> Result<JoinHandle<()>>

Start the container supervisor background task

This spawns a background task that monitors containers for crashes and enforces the on_panic error policy.

Errors

Returns an error if no container supervisor is configured.

Returns

A JoinHandle for the supervisor task.

pub fn shutdown_container_supervisor(&self)

Shutdown the container supervisor

pub async fn get_container_supervised_state( &self, container_id: &ContainerId, ) -> Option<SupervisedState>

Get the supervised state of a container

pub async fn take_supervisor_events(&self) -> Option<Receiver<SupervisorEvent>>

Get supervisor events receiver

Note: This can only be called once; the receiver is moved to the caller.

pub async fn deploy_with_dependencies( &self, services: HashMap<String, ServiceSpec>, ) -> Result<()>

Deploy multiple services respecting their dependency order

This method:

1. Builds a dependency graph from the services
2. Validates no cycles exist
3. Computes topological order (services with no deps first)
4. For each service in order, waits for dependencies then starts the service

Arguments

• services - Map of service name to service specification

Errors

• Returns AgentError::InvalidSpec if there are cyclic dependencies
• Returns AgentError::DependencyTimeout if a dependency times out with on_timeout: fail

pub async fn check_dependencies(&self, deps: &[DependsSpec]) -> Result<bool>

Check if all dependencies for a service are currently satisfied

This is a one-shot check (no waiting). Useful for pre-flight validation.

Errors

Returns an error if a dependency check fails unexpectedly.

pub async fn upsert_service( &self, name: String, spec: ServiceSpec, ) -> Result<()>

Add or update a workload (service, job, or cron)

This method handles different resource types appropriately:

• Service: Traditional long-running containers with scaling and health checks
• Job: Run-to-completion workloads triggered on-demand (stores spec for later)
• Cron: Scheduled run-to-completion workloads (registers with cron scheduler)

Errors

Returns an error if service creation, scaling, or cron registration fails.

pub async fn scale_service(&self, name: &str, replicas: u32) -> Result<()>

Scale a service. Cluster-aware: if this node has a Cluster handle and we’re not the leader, forward to the leader; if leader, compute affinity-aware placement and dispatch each node its share via dispatch_scale_distributed; else (single-node) just scale locally.

Errors

Returns an error if scaling fails on any participating node.

pub async fn scale_service_local(&self, name: &str, replicas: u32) -> Result<()>

Local (single-node) scale: directly creates/destroys containers on this node only. Called by:

• scale_service in single-node mode (when self.cluster is None).
• The /api/v1/internal/scale handler (which the leader’s Cluster::dispatch_scale HTTP-POSTs to, bottoming out the recursive loop on each receiving node).
• The cluster impls’ local_dispatch closure (for the leader’s own share — short-circuited to avoid a localhost round-trip).

Errors

Returns an error if the service is not found or scaling fails.

pub async fn service_replica_count(&self, name: &str) -> Result<usize>

Get service replica count

Errors

Returns an error if the service is not found.

pub async fn remove_service(&self, name: &str) -> Result<()>

Remove a workload (service, job, or cron)

This method handles cleanup for different resource types:

• Service: Unregisters proxy routes, supervisor, and removes from service map
• Job: Unregisters from job executor
• Cron: Unregisters from cron scheduler

Errors

Returns an error if the service cannot be removed or scale-down fails.

pub async fn service_infrastructure( &self, name: &str, ) -> Option<(bool, bool, bool)>

Introspect service infrastructure wiring. Returns (has_overlay, has_proxy, has_dns), or None if service not found.

pub async fn list_services(&self) -> Vec<String>

List all services

pub async fn get_service_logs( &self, service_name: &str, tail: usize, instance: Option<&str>, ) -> Result<Vec<LogEntry>>

Get logs for a service, aggregated from all container replicas.

Arguments

• service_name - Name of the service to fetch logs for
• tail - Number of lines to return per container (0 = all)
• instance - Optional specific instance (container ID suffix like “1”, “2”)

Errors

Returns an error if the service or instance is not found.

Returns

Structured log entries from all (or specific) container replicas. Each entry has its service and deployment fields populated when available.

pub async fn get_service_containers( &self, service_name: &str, ) -> Vec<ContainerId>

Get all container IDs for a specific service

Returns an empty vector if the service doesn’t exist.

Arguments

• service_name - Name of the service to query

Returns

Vector of ContainerIds for all replicas of the service

pub async fn get_service_container_infos( &self, service_name: &str, ) -> Vec<ContainerInfo>

Get per-container info (id, image, real state, pid, overlay IP) for a specific service.

Unlike get_service_containers (which returns ids only), this surfaces the REAL image reference and lifecycle state of each live container so the API/ps can report them accurately.

Returns an empty vector if the service doesn’t exist.

pub async fn local_service_state(&self, service: &str) -> NodeServiceState

This node’s local view of service (running replica count, health, containers), used for cluster-wide aggregation. Served by the internal /api/v1/internal/services/{svc}/state endpoint and used as the local part of Self::cluster_service_states.

pub async fn cluster_service_states( &self, service: &str, ) -> Vec<NodeServiceState>

Cluster-wide per-node states for service: this node’s local view plus every other node’s (fetched via the cluster handle’s fetch_remote_service_states). When not clustered, returns just the local view. This is the source of truth for distributed-service replica counts, health, and the ps container listing on the leader.

pub async fn exec_in_container( &self, service_name: &str, replica: Option<u32>, cmd: &[String], ) -> Result<(i32, String, String)>

Execute a command inside a running container for a service

Picks a specific replica if provided, otherwise uses the first available container.

Arguments

• service_name - Name of the service
• replica - Optional replica number to target
• cmd - Command and arguments to execute

Errors

Returns an error if the service or replica is not found, or if exec fails.

Panics

Panics if no replica is specified and the container list is unexpectedly empty after the emptiness check (should not happen in practice).

Returns

Tuple of (exit_code, stdout, stderr)

pub async fn list_container_views(&self) -> Vec<DeploymentContainerView>

List every live container across all services, enriched with the data a Docker ps row needs and the data the Docker-name resolver needs.

For each running container this surfaces the deployment name, the service name, the concrete ContainerId, the compose container_name: label (when set, the user-facing Docker name), the real image, the lifecycle state, and the service’s published port mappings. Used by the unified container-name resolver and by docker ps so compose deployments show up and resolve by their container_name.

pub async fn resolve_container_name(&self, name: &str) -> Option<ContainerId>

Resolve a Docker-style container name/id to a live deployment ContainerId.

Matching precedence (first hit wins):

1. The compose container_name: label (e.g. forgejo-e2e).
2. The conventional compose names {deployment}-{service}-{replica} and {deployment}_{service}_{replica} (replica is 1-based, mirroring Docker Compose; ContainerId.replica is 0-based so we add 1).
3. The bare service name ({service}), targeting its first replica.
4. The ContainerId Display form.

Returns None when nothing matches a running container.

pub async fn exec_in_container_id_with_opts( &self, id: &ContainerId, opts: &ExecOptions, ) -> Result<(i32, String, String)>

Execute a command in a specific deployment container (by its concrete ContainerId) honouring Docker exec options (--user, -w, -e).

Routes through Runtime::exec_with_opts so runtimes that support dropping to a uid/gid + chdir + env injection (macOS VZ-Linux) apply them; others fall back to a plain buffered exec.

Errors

Propagates the runtime’s exec error.

pub async fn trigger_job( &self, name: &str, trigger: JobTrigger, ) -> Result<JobExecutionId>

Trigger a job execution

Arguments

• name - Name of the registered job
• trigger - How the job was triggered (endpoint, cli, etc.)

Returns

The execution ID for tracking the job

Errors

• Returns error if job executor is not configured
• Returns error if the job is not registered

pub async fn get_job_execution( &self, id: &JobExecutionId, ) -> Option<JobExecution>

Get the status of a job execution

Arguments

• id - The execution ID returned from trigger_job

Returns

The job execution details, or None if not found

pub async fn list_job_executions(&self, name: &str) -> Vec<JobExecution>

List all executions for a specific job

Arguments

• name - Name of the job

Returns

Vector of job executions for the specified job

pub async fn cancel_job(&self, id: &JobExecutionId) -> Result<()>

Cancel a running job execution

Arguments

• id - The execution ID to cancel

Errors

Returns error if job executor is not configured or if cancellation fails

pub async fn trigger_cron(&self, name: &str) -> Result<JobExecutionId>

Manually trigger a cron job (outside of its schedule)

Arguments

• name - Name of the cron job

Returns

The execution ID for tracking the triggered job

Errors

Returns error if cron scheduler is not configured or job not found

pub async fn set_cron_enabled(&self, name: &str, enabled: bool)

Enable or disable a cron job

Arguments

• name - Name of the cron job
• enabled - Whether to enable or disable the job

pub async fn list_cron_jobs(&self) -> Vec<CronJobInfo>

List all registered cron jobs

pub fn start_cron_scheduler(&self) -> Result<JoinHandle<()>>

Start the cron scheduler background task

This spawns a background task that checks for due cron jobs every second. Returns a JoinHandle that can be used to wait for the scheduler to stop.

Errors

Returns error if cron scheduler is not configured

pub fn shutdown_cron(&self)

Shutdown the cron scheduler