skywatch.blue / skywatch-phash-rs
A rust implementation of skywatch-phash
fork atom
skywatch-phash-rs / src / moderation / README.md
at main 2.9 kB view raw view code
Skywatch ```text Add documentation ```
c36259f8

Moderation Module#

Purpose#

This module is responsible for all interactions with the Ozone moderation service. It provides functions to label or report accounts and posts based on the matches found by the processing workers. It is designed to be robust, preventing duplicate actions and respecting API rate limits.

Key Components#

post.rs & account.rs#

These files provide high-level functions for taking action on a specific subject (either a post or an account). For example, post::label_post(...) or account::report_account(...). Their primary responsibility is to construct the correct EmitEvent object using jacquard-api types and pass it to the send_moderation_event helper.

helpers.rs#

This file contains shared logic to reduce duplication:

  • send_moderation_event(): The core of the module. All actions funnel through this function, which first waits for the global RateLimiter and then uses the authenticated agent to send the event to Ozone.
  • build_timestamped_comment(): Creates the detailed comment string that is attached to every moderation action, providing context for human reviewers.
  • build_mod_tool_meta(): Constructs the metadata object attached to events, including the phash and a link to the post.

rate_limiter.rs#

  • RateLimiter: A crucial, thread-safe rate limiter built using the governor crate. A single instance is shared across all workers. Before any worker calls the Ozone API, it must await the limiter, which ensures the application as a whole does not exceed the configured request rate (e.g., 10 requests/sec).

claims.rs#

  • This component provides a distributed locking/deduplication mechanism using Redis. Its purpose is to prevent the system from taking the same action on the same subject multiple times. For example, if two workers simultaneously find a match on the same post, claims::claim_post_report() ensures that only the first worker to acquire the Redis lock (a key with a 24-hour TTL) will actually send the report.

High-Level Flow#

  1. A worker in the queue module finds a phash match and decides to take action.
  2. It calls a function like moderation::post::report_post().
  3. Inside the worker, a moderation_action! macro first calls claims::claim_post_report() to ensure this exact action hasn't already been performed recently.
  4. If the claim is successful, report_post() is called. It constructs the EmitEvent payload.
  5. It then calls helpers::send_moderation_event() with this payload.
  6. send_moderation_event() first awaits the rate_limiter to get a green light.
  7. Finally, it uses the authenticated agent to send the request to the Ozone API.

This architecture ensures that all actions are rate-limited globally and are automatically deduplicated across the entire distributed system of workers.