parrhesia/docs/MARMOT_OPERATIONS.md

Marmot operations guide (relay operator tuning)

This document captures practical limits and operational defaults for Marmot-heavy traffic (443, 445, 10051, wrapped 1059, optional media/push flows).

1) Recommended baseline limits

Use these as a starting point and tune from production telemetry.

config :parrhesia,
  limits: [
    max_filter_limit: 500,
    max_filters_per_req: 16,
    max_outbound_queue: 256,
    outbound_drain_batch_size: 64
  ],
  policies: [
    # Marmot group routing/query guards
    marmot_require_h_for_group_queries: true,
    marmot_group_max_h_values_per_filter: 32,
    marmot_group_max_query_window_seconds: 2_592_000,

    # Kind 445 retention
    mls_group_event_ttl_seconds: 300,

    # MIP-04 metadata controls
    marmot_media_max_imeta_tags_per_event: 8,
    marmot_media_max_field_value_bytes: 1024,
    marmot_media_max_url_bytes: 2048,
    marmot_media_allowed_mime_prefixes: [],
    marmot_media_reject_mip04_v1: true,

    # MIP-05 push controls (optional)
    marmot_push_server_pubkeys: [],
    marmot_push_max_relay_tags: 16,
    marmot_push_max_payload_bytes: 65_536,
    marmot_push_max_trigger_age_seconds: 120,
    marmot_push_require_expiration: true,
    marmot_push_max_expiration_window_seconds: 120,
    marmot_push_max_server_recipients: 1
  ]

2) Index expectations for Marmot workloads

The Postgres adapter relies on dedicated partial tag indexes for hot Marmot selectors:

• event_tags_h_value_created_at_idx for #h group routing
• event_tags_i_value_created_at_idx for #i keypackage reference lookups

Query-plan regression tests assert these paths remain usable for heavy workloads.

3) Telemetry to watch

Key metrics for Marmot traffic and pressure:

• parrhesia.ingest.duration.ms{traffic_class="marmot|generic"}
• parrhesia.query.duration.ms{traffic_class="marmot|generic"}
• parrhesia.fanout.duration.ms{traffic_class="marmot|generic"}
• parrhesia.connection.outbound_queue.depth{traffic_class=...}
• parrhesia.connection.outbound_queue.pressure{traffic_class=...}
• parrhesia.connection.outbound_queue.pressure_events.count{traffic_class=...}
• parrhesia.connection.outbound_queue.overflow.count{traffic_class=...}

Operational target: keep queue pressure below sustained 0.75 and avoid overflow spikes during 445 bursts.

4) Fault and recovery expectations

During storage outages, Marmot group-flow writes must fail with explicit OK false errors. After recovery, reordered group events should still query deterministically by created_at DESC, id ASC.