# ============================================================
# MailboxGUI Network Configuration
# ============================================================
#
# This file controls optional multi-backend network mode.
#
# File location after startup:
# /plugins/MailboxGUI/network/config.yml
#
# IMPORTANT:
# - Network mode is disabled by default.
# - Single-server setups do not need Redis.
# - Single-server setups do not need MySQL.
# - Redis settings exist in this file, but there is NO redis.enabled option.
# - Redis is ignored when network.enabled is false.
# - Redis is required when network.enabled is true.
# - Network mode requires shared MySQL/MariaDB storage.
# - YAML and SQLite are not valid storage modes when network mode is enabled.
# - Keep backend and database host clocks synchronized (for example with NTP).
#   Presence, scheduling and companion lease decisions compare timestamps; a
#   database-clock write timestamp does not remove client clock-skew risks.
#
# Recommended use:
# - Leave network.enabled false for normal single-server setups.
# - Enable network mode only when running MailboxGUI on multiple backend servers
#   that share the same MySQL/MariaDB database and Redis instance.
#
# ============================================================

config-version: 4

network:
  # Master toggle for MailboxGUI network mode.
  #
  # false:
  # - MailboxGUI works like a normal single-server plugin.
  # - Redis is not contacted.
  # - YAML, SQLite, and MySQL are valid storage options.
  #
  # true:
  # - MailboxGUI runs in multi-backend network mode.
  # - Active storage must be MYSQL/MariaDB.
  # - Redis must be reachable.
  # - If MySQL or Redis validation fails, MailboxGUI disables itself on startup
  #   to avoid running network mode without required shared services.
  # - /mba reload also reloads this file and restarts the network runtime.
  # - After validation, readiness requires an asynchronous backend ownership lease,
  #   Redis SUBSCRIBE acknowledgment, and healthy shared storage.
  # - Claims, kit usage, and delayed delivery wait for these readiness checks.
  # - Reload may return while the runtime is STARTING, before it becomes ready.
  # - If a reload validation fails while network.enabled is true, MailboxGUI
  #   disables itself to protect shared network mail data.
  enabled: false

  # Redis coordination namespace shared by all backends in this MailboxGUI network.
  # Use only letters, numbers, dots, underscores or hyphens.
  # mailboxgui preserves the existing channel and lock-key names.
  # Other values isolate Redis channels and ownership/lock keys from another network.
  # Keep this identical across backends in the same network.
  # Independent networks need distinct shared MySQL databases AND distinct namespaces.
  # The namespace isolates Redis and companion-coordination records, not shared
  # mail, player, registration or scheduled-state MySQL tables.
  # Stop all network backends before changing this value, then update every backend.
  # Never mix namespaces while sharing one MySQL mail database: separate Redis locks
  # cannot safely coordinate concurrent access to the same mail data.
  namespace: mailboxgui

  # Unique ID for this backend server.
  #
  # Every backend must have a different server-id.
  # A duplicate ID pauses the offending runtime to protect shared mail.
  # Give that backend a unique ID, then run /mba reload to retry.
  #
  # Examples:
  # server-id: live
  # server-id: legacy
  # server-id: lobby
  # server-id: survival
  # server-id: creative
  #
  # Do not use spaces or color codes here.
  server-id: server1

  # Friendly display name for this backend.
  #
  # This may be shown in admin output, recipient status lore, and logs.
  #
  # Examples:
  # server-display-name: ImagineCraft1.0
  # server-display-name: Legacy
  # server-display-name: Lobby
  #
  # Color codes are not recommended here because this value may be used in logs.
  server-display-name: 'Server 1'

gui:
  # Active/validated only when global config.yml gui-customization.enabled is true
  # AND network.enabled is true. Disabled customization ignores these settings.
  # Scope covers themed icons only, never arbitrary inventory layouts or actions.
  # shared: one authoritative icon configuration across backends (default).
  # backend-local: each backend keeps its own themed icon configuration.
  # A resource pack may contain all themed assets for every backend.
  # gui.yml itemsadder-item: namespace:id works with shared and backend-local appearances.
  # Every rendering backend needs compatible ItemsAdder and the referenced item registry loaded locally.
  # Shared GUI IDs do not synchronize ItemsAdder content, prove pack acceptance, or validate model files.
  # Non-null itemsadder-item takes precedence over same-layer material/custom-model-data/item-model fields.
  # Missing/unready/incompatible ItemsAdder or invalid/unknown IDs retain the preceding inherited/built-in appearance.
  # Same-layer sibling fields are not fallback fields; configure an earlier layer or set itemsadder-item to null.
  # ItemsAdder owns pack building/merging, hosting and deployment; MailboxGUI never sends a second pack.
  # Include all referenced assets for all themes in its deployed pack, valid for each server/client version.
  # After ItemsAdder content changes use /iareload and rebuild/deploy its pack when needed; use /mba reload for GUI edits.
  # In shared scope, edit/reload the authoritative GUI backend; load ItemsAdder content on every rendering backend.
  # Global gui-customization.enabled and required auto detection remain authoritative with ItemsAdder.
  # Player On/Off/Auto preferences are shared in BOTH scopes; actual pack-loaded status stays local.
  scope: shared

  # Optional authoritative publisher backend ID for shared scope only.
  # Empty selects the authoritative first publisher, not each backend's local file.
  # Ignored in backend-local scope. Keep the shared policy identical on all backends.
  shared-main-backend: ''

redis:
  # Redis connection settings.
  #
  # There is intentionally NO redis.enabled setting.
  #
  # Redis behavior:
  # - Ignored when network.enabled is false.
  # - Required and validated when network.enabled is true.
  # - Recovery uses Redis Streams (Redis 5 or newer) as bounded event history.
  # - Up to 4096 recent events are retained; older notifications may not replay.
  # - Enable Redis persistence and protect its files if event history must survive
  #   a Redis restart. Shared mail itself remains in MySQL/MariaDB.
  # - Unsynced events and replay cursors are kept under network/recovery locally.
  #   Preserve this folder across plugin updates; do not share it between servers.
  # - Recovery checks saved storage revisions and refreshes live views; it never
  #   sends persisted mail again or repeats claims, COD payments, or payouts.
  # - A newly configured backend starts from the current event tail, not old alerts.
  # - The local outbox refuses new recovery entries when its bounded capacity is
  #   exhausted; it does not silently discard pending entries. Check console warnings.
  # - Replay is bounded recovery, not an exactly-once notification guarantee.
  #   Lost/trimmed event history may require cache refresh without replaying old alerts.
  #
  # All backend servers in the same MailboxGUI network should point
  # to the same Redis server.

  # Redis host or IP address.
  #
  # For Redis on the same machine:
  # host: 127.0.0.1
  #
  # For Redis on another machine:
  # host: redis.example.com
  host: 127.0.0.1

  # Redis port.
  #
  # Default Redis port is 6379.
  port: 6379

  # Redis password.
  #
  # Leave blank if your Redis server does not require authentication.
  #
  # Example:
  # password: 'yourRedisPassword'
  password: ''

  # Redis database number.
  #
  # Most setups can leave this at 0.
  # Use a different database number only if you intentionally separate data
  # between multiple applications on the same Redis server.
  # This selects the database for keys/Streams, not Pub/Sub channels: channels
  # span Redis databases. Distinct networks still require distinct namespaces.
  database: 0

  # Enables SSL/TLS for the Redis connection.
  #
  # Only set true if your Redis server is configured for SSL/TLS.
  # Most local Redis installs use false.
  use-ssl: false

  channels:
    # Main network event channel.
    #
    # Used for mail delivery refresh events and general backend sync messages.
    network: 'mailboxgui:network'

    # Presence channel.
    #
    # Auxiliary presence publication channel. The runtime subscriber consumes the
    # main network channel; durable presence lookup uses shared MySQL player data.
    presence: 'mailboxgui:presence'

    # Cache refresh channel.
    #
    # Reserved for cache invalidation and future targeted reload messages.
    cache: 'mailboxgui:cache'

    # Lock channel.
    #
    # Reserved for lock-related diagnostics/future lock messages.
    # Actual lock ownership is stored using Redis keys, not only this channel.
    locks: 'mailboxgui:locks'

  connection:
    # Redis connection timeout in milliseconds.
    #
    # Bounds socket operations and subscriber authentication/SUBSCRIBE handshakes.
    # It is not a total timeout for every multi-step operation. Network Tools probes
    # separately cap Redis socket timeouts at five seconds.
    timeout-millis: 5000

    # Subscriber retries per outage, after the initial connection attempt.
    # 0 = make the initial attempt only, with no retries.
    # The retry budget resets after Redis acknowledges SUBSCRIBE.
    # Once retries are exhausted, use /mba reload or restart to reconnect.
    reconnect-attempts: 3

    # Delay between Redis reconnect attempts.
    reconnect-delay-seconds: 5

presence:
  # Enables network player presence tracking.
  #
  # This lets MailboxGUI know which backend a player is online on.
  #
  # Used by:
  # - Online/offline recipient filters
  # - Admin online player targeting
  # - Recipient GUI status lore
  # false stops player presence writes and omits public API presence snapshots;
  # unknown presence is not proof that a player is offline. Presence-dependent
  # scheduled checks and companion recipient policies may wait for authoritative data.
  # Backend compatibility heartbeats, ownership and readiness remain active.
  enabled: true

  # Backend ownership/compatibility heartbeat interval and, when enabled, player updates.
  # Must be less than stale-after-seconds even when player presence is disabled.
  heartbeat-seconds: 30

  # How long a player presence record is considered fresh.
  #
  # Expired online entries are excluded from online network audiences.
  # The companion API marks stale presence as unknown, not confirmed offline.
  # Must be greater than heartbeat-seconds; allow headroom for backend lag.
  stale-after-seconds: 90

  # Shows backend name in recipient GUI lore.
  #
  # Example:
  # Online on Legacy
  show-server-in-recipient-list: true

  # Shows last known world in recipient GUI lore.
  #
  # Example:
  # World: Croatan
  show-world-in-recipient-list: true

recipients:
  # Uses shared MailboxGUI player data for recipient lookup.
  #
  # This should remain true in network mode so players known on one backend
  # can be found from another backend.
  use-shared-player-data: true

  # Uses network presence for online/offline recipient filtering.
  #
  # This lets Online Players include players online on other backend servers.
  use-network-presence: true

  # Allows local world/playerdata fallback if a typed recipient is not found
  # in shared MailboxGUI data or the network player index.
  #
  # Useful for old/legacy servers where players have joined before but do not
  # yet have MailboxGUI data.
  #
  # If false, typed recipient lookup in network mode only trusts shared/network data.
  allow-local-playerdata-fallback: true

compatibility:
  multiversion-backends:
    # Enables advanced mixed-version backend compatibility.
    #
    # false:
    # - Default and safest behavior.
    # - Every backend in the MailboxGUI network must use the same compatibility profile.
    # - Profile checks include Minecraft version, Bukkit/Paper data version,
    #   MailboxGUI version, network protocol version, package manifest version,
    #   and package serializer profile.
    # - If a mismatched backend is detected, MailboxGUI will fail safely to
    #   protect shared mail data.
    #
    # true:
    # - Allows supported Minecraft versions from 1.18.2 through 1.21.11
    #   and 26.1 through 26.3 to share this network.
    # - Every backend must run the same MailboxGUI Premium build with compatible
    #   mail data, network protocol, and package manifest versions.
    # - Known Bukkit map and Paper/Purpur native-byte serializers may coexist.
    #   A backend without the required item codec cannot claim that payload.
    # - Item compatibility is checked per package entry, not only by the
    #   Minecraft version of the sending backend. Unknown materials and
    #   unreadable custom item data remain restricted without losing their bytes.
    # - Admin tools do not override backend targets or item compatibility.
    # - Unknown backend profiles or incompatible mail schemas still stop
    #   network startup. This toggle does not bypass data-safety validation.
    # - Test every backend combination before enabling this in production.
    enabled: false

  packages:
    # Controls package behavior when a backend cannot support one or more
    # materials inside a package created on another Minecraft version.
    # This controls claiming only. Packages are still delivered and visible
    # across the network even when their contents cannot be claimed here.
    #
    # false:
    # - The whole package is view-only on incompatible backends.
    # - Players must claim it from a backend that supports every item.
    #
    # true:
    # - Compatible entries can be claimed when the package framing and manifest
    #   are valid and the remaining original item records can be retained exactly.
    # - Unsupported items stay in the package and use the unavailable-item display.
    #   Premium gui.yml can customize that display, not its claim restrictions.
    # - Plain vanilla items may use a verified portable representation written
    #   by the sender. Custom item metadata is never stripped to permit a claim.
    # - An unreadable entry stays blocked; corrupt package framing blocks claims.
    #   This option does not discard unsupported item data or change mail targets.
    #
    # Admin player-inbox and shared-inbox views can inspect contents with either
    # value. Admins can take only supported entries on an allowed target backend;
    # unreadable entries remain in the package, and pending COD needs acceptance.
    #
    # This is a local backend policy. If only one backend enables this, only
    # that backend allows partial claims. If every backend uses the same value,
    # the whole network behaves consistently.
    allow-partial-unsupported-item-claims: false

backend-groups:
  # Optional named backend groups for advanced Premium network targeting.
  #
  # These groups are used by mail/package metadata with the BACKEND_GROUP
  # target type. A backend can claim/process that mail only when its
  # network.server-id is listed in the matching group.
  #
  # Use lowercase IDs that match network.server-id values across your backends.
  #
  # Example:
  # groups:
  #   modern:
  #     - survival
  #     - creative
  #   legacy:
  #     - legacy
  # Keep group names and members identical on every backend using group targets.
  # This file is reloaded locally; editing one backend does not distribute its YAML.
  groups: {}

sync:
  kit:
    # Enables network-aware mailbox kit usage sync.
    #
    # true:
    # - /mb kit usage is saved in shared player data and remote backend caches
    #   are refreshed after kit usage or kit notification changes.
    enabled: true

    # Optional main backend for kit command ownership.
    #
    # Leave empty to allow kit claims on any backend.
    # Set to a network.server-id to make only that backend process /mb kit.
    main-backend: ''

  # Inbox and shared mail data synchronization is mandatory in network mode.
  # Remote mail events refresh live inboxes and caches; this cannot be disabled.

  # Refresh physical new-mail notification visuals after remote mail events.
  # This visual switch does not disable mail delivery or mandatory inbox synchronization.
  refresh-notifications-on-mail-event: true

  # Refresh registered player mailbox caches after remote register/unregister events.
  refresh-mailboxes-on-registration-change: true

  # Synchronize Public Access Mailboxes/NPCs between backends.
  #
  # Remote changes refresh locally cached public access registrations.
  # The legacy setting name below remains unchanged for compatibility.
  refresh-post-offices-on-change: true

  # Refresh the local item template cache after remote template changes.
  refresh-item-templates-on-change: true

locks:
  # Enables Redis-backed network locks.
  #
  # Required when network.enabled is true; startup validation rejects disabled locks.
  # false is allowed when network.enabled is false.
  #
  # Locks prevent multiple backend servers from processing the same shared
  # mail item at the same time.
  #
  # Protected examples:
  # - COD accept/decline
  # - Money mail claim
  # - Normal package receive session
  # - Delayed mail delivery
  #
  # Keep true for network mode.
  enabled: true

  # Renewable Redis lease duration for money mail claims and package receive sessions.
  #
  # Active locks renew automatically; this is not a maximum package GUI open time.
  # Allow enough time for Redis/network delays between renewals.
  # After a backend stops renewing, Redis expires the lease within this duration.
  # Longer leases can delay recovery after a crash; shorter leases tolerate less lag.
  #
  # Recommended default: 120 seconds.
  mail-claim-lock-seconds: 120

  # Renewable Redis lease duration for COD accept/decline transactions.
  #
  # COD actions are quick transactions:
  # - Check COD package
  # - Withdraw/deposit or create COD payment mail
  # - Convert/return package
  # - Save mailbox data
  #
  # Recommended default: 15 seconds.
  cod-transaction-lock-seconds: 15

  # Renewable Redis lease duration for delayed mail delivery.
  #
  # Prevents multiple backend servers from delivering the same delayed mail
  # queue entry at the same time.
  #
  # Recommended default: 30 seconds.
  delayed-mail-lock-seconds: 30

delayed-mail:
  # Maximum number of due delayed mail entries a backend may claim/process
  # during one scan cycle.
  claim-batch-size: 25

  # Maximum wall-clock interval between shared queue scans, in seconds.
  # Known future delivery deadlines wake the worker sooner than this interval.
  # Delivery runs on the server thread; server stalls, locks and batching may delay it.
  scan-interval-seconds: 30

scheduled-mail:
  # Default execution owner for shared scheduled tasks without network.owner.
  # distributed = eligible backends coordinate one shared execution.
  # server:<server-id> = only the identified backend may execute the task.
  # Use a unique, active network.server-id; an unavailable owner pauses its tasks.
  # Per-task network.owner takes precedence. Legacy network-owner-mode is accepted
  # when network.owner is absent; use network.owner for new tasks.
  # Per-task network.scope defaults to shared. backend-local tasks run independently
  # on their own backend and are not one globally shared execution.
  # This default-owner applies only to shared tasks. A backend-local task without
  # an explicit owner runs locally; an explicit different backend owner is invalid.
  # Conflicting shared definitions or pending definition checks pause execution;
  # a shared lock alone does not resolve conflicting definitions.
  # recipients.scope defaults to network and is independent of execution ownership.
  # ONLINE_PLAYERS and PERMISSION checks use authoritative owning backends.
  # Offline permission evaluation is unsupported and pauses the task.
  # Define matching PERMISSION tasks on every backend that may host eligible
  # players; missing/stale eligibility proofs pause rather than guess permissions.
  # Per-task delivery.target defaults to network. Other targets: current-backend,
  # backends, exclude-backends, or group. Use delivery.backends for backend lists
  # and delivery.group for a configured backend group; keep group definitions consistent.
  # Shared distributed tasks cannot use the ambiguous current-backend target.
  # Mail delivery targets are independent of task execution and recipient scope.
  # See the Premium scheduled-mail/scheduled-mail.yml reference for disabled examples.
  # That file is generated only if missing; existing tasks/files are not overwritten.
  # This setting does not restrict normal delayed-mail queue delivery.
  default-owner: distributed


debug:
  # Enables extra network debug logs.
  #
  # Keep false for normal servers.
  enabled: false

  # Logs Redis publish/subscriber activity; also requires debug.enabled: true.
  #
  # Useful when diagnosing network sync issues.
  # Can be noisy on active servers.
  log-redis-messages: false

  # Logs presence heartbeat activity; also requires debug.enabled: true.
  #
  # Useful when diagnosing cross-server online status.
  # Can be noisy on active servers.
  log-presence-heartbeats: false