# ============================================================
# 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.
#
# 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: 1

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.
  # - Startup will fail safely if MySQL or Redis validation fails.
  enabled: false

  # Unique ID for this backend server.
  #
  # Every backend must have a different server-id.
  #
  # Examples:
  # - live
  # - legacy
  # - lobby
  # - survival
  # - 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:
  # - Live
  # - Legacy
  # - Lobby
  #
  # Color codes are not recommended here because this value may be used in logs.
  server-display-name: 'Server 1'

  # Network mode requires shared MySQL/MariaDB storage.
  #
  # This should remain true. YAML and SQLite cannot safely share mail data
  # between backend servers.
  #
  # If network.enabled is true and active storage is YAML or SQLite,
  # MailboxGUI will disable itself to protect shared mail data.
  require-shared-storage: true

mysql:
  # Required active storage type when network mode is enabled.
  #
  # MailboxGUI still uses the main config.yml storage.mysql section
  # for the real MySQL/MariaDB connection.
  #
  # This setting is used for validation and admin-facing error messages.
  # Do not change unless the plugin adds another shared SQL backend later.
  require-active-storage-type: MYSQL

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.
  #
  # 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.
  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.
    #
    # Used for backend heartbeat messages and cross-server online status.
    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.
    #
    # If Redis does not respond within this time, validation or publish actions fail.
    timeout-millis: 5000

    # Number of reconnect attempts for network runtime tasks.
    #
    # This is mainly used by subscriber/reconnect behavior.
    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
  enabled: true

  # How often this backend updates/publishes its online player presence.
  heartbeat-seconds: 30

  # How long a player presence record is considered fresh.
  #
  # If another backend stops updating a player for this many seconds,
  # that player is treated as offline for network recipient filtering.
  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

sync:
  # Refresh local inbox/mail data when another backend reports new mail.
  refresh-inbox-on-mail-event: true

  # Refresh mailbox notification visuals when another backend reports new mail.
  refresh-notifications-on-mail-event: true

  # Reserved for future mailbox registration sync.
  #
  # Intended use:
  # If a mailbox is registered/unregistered on one backend, other backends
  # can refresh cached mailbox data.
  refresh-mailboxes-on-registration-change: true

  # Reserved for future Post Office sync.
  #
  # Intended use:
  # If a Post Office mailbox/NPC changes on one backend, other backends
  # can refresh local cached Post Office state.
  refresh-post-offices-on-change: true

  # Reserved for future item template sync.
  #
  # Intended use:
  # If item templates change on one backend, other backends can refresh
  # their template cache.
  refresh-item-templates-on-change: true

locks:
  # Enables Redis-backed network locks.
  #
  # Strongly recommended when network.enabled is true.
  #
  # 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
  #
  # Leave true unless diagnosing a specific Redis lock issue.
  enabled: true

  # Lock duration for money mail claims and normal package receive sessions.
  #
  # This must be long enough for a player to open a package GUI and remove items.
  #
  # If too short:
  # - A package GUI could remain open after the lock expires.
  #
  # If too long:
  # - A crashed/abandoned claim may stay blocked longer before Redis expires it.
  #
  # Recommended default: 120 seconds.
  mail-claim-lock-seconds: 120

  # Lock 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

  # Lock 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:
  # Controls how delayed mail is processed in network mode.
  #
  # distributed:
  # - Every backend may scan the delayed mail queue.
  # - Redis locks prevent duplicate delivery.
  #
  # For now, distributed is the intended mode.
  network-owner-mode: distributed

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

  # How often delayed mail is scanned.
  scan-interval-seconds: 30

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

  # Logs Redis publish/subscriber messages.
  #
  # Useful when diagnosing network sync issues.
  # Can be noisy on active servers.
  log-redis-messages: false

  # Logs presence heartbeat messages.
  #
  # Useful when diagnosing cross-server online status.
  # Can be noisy on active servers.
  log-presence-heartbeats: false