Skip to main content

AFS_AETHER_WORKER_ID

Deep-dive reference for:

  • AFS_AETHER_WORKER_ID

Status​

  • active-or-experimental

Audience​

  • production/user

Type and Default​

  • Type: UUID string.
  • Required format: canonical UUID accepted by Uuid::parse_str.
  • Default behavior:
    • If bridge mode is enabled and no worker ID is provided, Aether generates a new UUID (v4).
    • If bridge mode is disabled, bridge worker identity is not used.

What It Does​

Identifies a specific Aether bridge worker instance to server-side bridge services.

This ID is used when Aether:

  • subscribes to changefeed updates (worker_id in SubscribeSessionUpdatesRequest)
  • sends writeback mutations (mount_worker_id in MountMutationEnvelope)
  • processes mutation ACKs (mount_worker_id in MountMutationAck)

On the server side, worker identity is used for:

  • worker registration/tracking
  • lease ownership/revocation paths
  • per-worker changefeed ack tracking (worker_id + session_id)
  • mutation idempotency keys (session_id + mount_worker_id + mutation_id)

Input Surfaces​

  • Env: AFS_AETHER_WORKER_ID=<uuid>
  • Config file (aether.toml):
bridge_enabled = true

[bridge]
worker_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

There is no dedicated CLI flag for worker ID in aether mount.

Resolution and Precedence​

When bridge mode is enabled:

  1. Environment (AFS_AETHER_WORKER_ID)
  2. Config file ([bridge].worker_id)
  3. Auto-generated UUID

If the provided value is not a valid UUID, config resolution fails at startup.

Why Uniqueness Matters​

Worker ID should be unique per concurrently running mount instance.

If two live workers use the same ID for the same session, server-side tracking can conflate them (for example idempotency/resume/lease ownership behavior), because those systems key state by worker identity.

Operator Guidance​

  • Recommended default: leave unset and let Aether generate a UUID.
  • Set explicitly only when you need a stable identity for operational/debug correlation across restarts.
  • Do not reuse the same worker ID across multiple simultaneously running mounts on the same session.

Primary Implementation Sources​

  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/config/types/parse_helpers.rs
  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/config/types/model_defaults.rs
  • packages/aether-remote/src/mount/orchestrator.rs
  • packages/aether-remote/src/changefeed/applier.rs
  • proto/aetherfs/v1/filesystem.proto
  • packages/afs-server/src/bridge/worker_registry.rs
  • packages/afs-grpc-services/svc-mount-worker/src/changefeed.rs
  • packages/afs-grpc-services/svc-mount-worker/src/idempotency.rs