Struct WriterHandle 

pub struct WriterHandle { /* private fields */ }

Cheap handle to the writer task. Clones share the same underlying mpsc channel; a drop of the last clone is a silent shutdown signal to the writer task (receiver closes). For a clean shutdown that releases the lease row, call WriterHandle::shutdown.

Implementations

impl WriterHandle

pub async fn apply_label(&self, req: ApplyLabelRequest) -> Result<LabelEvent>

Submit an apply-label request. Resolves when the writer has committed the transaction and broadcast the event, or returns an Err describing why the write was rejected.

pub async fn negate_label(&self, req: NegateLabelRequest) -> Result<LabelEvent>

Submit a negate-label request. Returns Error::LabelNotFound if no applied label currently exists for (service_did, uri, val).

pub async fn resolve_report( &self, req: ResolveReportRequest, ) -> Result<ResolvedReport>

Resolve a report, optionally applying a label in the same atomic transaction. The label INSERT + audit row + report UPDATE + resolution audit row all commit together or not at all; the label broadcast fires post-commit inside the writer task (§F5 + §F12 atomicity contract).

Errors:

• Error::ReportNotFound — report_id doesn’t exist.
• Error::ReportAlreadyResolved — report is not in the pending state. Handler maps to a generic InvalidRequest.

pub async fn sweep(&self, _req: SweepRequest) -> Result<SweepResult>

Trigger a §F4 retention sweep through the writer task. Loops over single-batch dispatches until a batch returns has_more = false, aggregating rows + duration. Other writer commands interleave between batches (single-writer invariant + bounded latency).

Returns rows_deleted = 0, batches = 0 when the writer was spawned with retention_days = None (sweep configured off): the first batch returns immediately and the loop exits with the no-op result.

pub async fn record_action( &self, req: RecordActionRequest, ) -> Result<RecordedAction>

Record a graduated-action moderation event (§F20 / #51). The writer validates inputs, computes the strike value at action time via the v1.4 calculators (#48/#49/#50/#51), inserts the subject_actions row, updates the strike-state cache, and writes a hash-chained audit_log row — all in a single transaction. Errors:

• Error::ReasonNotFound when a reason identifier is not declared in [moderation_reasons].
• Error::DurationRequiredForTempSuspension for temp_suspension without duration_iso.
• Error::DurationOnlyForTempSuspension for non-temp types with duration_iso set.
• Error::Signing for malformed subject / duration / etc.

pub async fn revoke_action( &self, req: RevokeActionRequest, ) -> Result<RevokedAction>

Revoke a previously-recorded action (§F20 / #51). Errors:

• Error::ActionNotFound when no row matches action_id.
• Error::ActionAlreadyRevoked when the row’s revoked_at is already non-NULL — the schema trigger forbids re-revocation; the handler catches it before the UPDATE.

pub async fn confirm_pending_action( &self, req: ConfirmPendingActionRequest, ) -> Result<ConfirmedPendingAction>

Confirm a pending policy action (§F22 / #74). The proposed action carried on the pending row is materialized as a real subject_actions row (actor_kind=‘moderator’, triggered_by_policy_rule preserves the rule that proposed it), labels emit per crate::labels::policy::LabelEmissionPolicy, the pending row’s resolution columns transition NULL → ‘confirmed’, and the strike-state cache is recomputed — all in one transaction under a single pending_policy_action_confirmed audit row. Errors:

• Error::PendingActionNotFound when no row matches pending_id.
• Error::PendingAlreadyResolved when the row’s resolution column is already non-NULL.
• Error::SubjectTakendown when the subject already carries an unrevoked Takedown — defensive guard against the auto-dismissal-on-takedown race (#76).

pub async fn dismiss_pending_action( &self, req: DismissPendingActionRequest, ) -> Result<DismissedPendingAction>

Dismiss a pending policy action (§F22 / #75). The pending row’s resolution columns transition NULL → ‘dismissed’ and a single hash-chained pending_policy_action_dismissed audit row commits with the UPDATE — no subject_actions row, no label emission, no strike-state change. The pending row stays in the table as forensic record (confirmed_action_id stays NULL since no action was created).

Errors:

• Error::PendingActionNotFound when no row matches pending_id.
• Error::PendingAlreadyResolved when the row’s resolution column is already non-NULL.

pub async fn append_audit(&self, row: AuditRowForAppend) -> Result<i64>

Append a hash-chained audit row through the writer task (#39). Used by in-process callers that don’t already hold a transaction — e.g., retentionSweep’s post-sweep audit row. Callers that have an open transaction (writer-internal handlers, flag_reporter) use crate::audit::append::append_in_tx directly so the audit row commits atomically with the rest of their work. Cross-process CLIs (publish/unpublish-service- record) use crate::audit::append::append_via_pool.

Returns the inserted audit_log.id.

pub fn subscribe(&self) -> Receiver<LabelEvent>

Subscribe to committed events. The returned receiver lags past the internal broadcast buffer; the consumer (subscribeLabels, #7) turns RecvError::Lagged into a connection close.

pub fn receiver_count(&self) -> usize

Count of live broadcast receivers. Exposed for test sync points (the WS handler subscribes asynchronously after upgrade; tests that want to emit an event “after the subscriber is ready” poll this until it reaches the expected count). Not a production hot path — broadcast::Sender::receiver_count walks an atomic chain.

pub fn shutdown_signal(&self) -> Receiver<bool>

Observe writer lifecycle. The returned receiver starts at false and flips to true once exactly, when the writer has accepted a shutdown command and is about to release the lease. Holders close downstream connections gracefully on the true transition.

pub async fn shutdown(&self) -> Result<()>

Explicit shutdown. Drains in-flight writes, releases the lease row, stops the heartbeat, and returns. Idempotent-ish: calling on an already-shut-down writer returns a channel-closed error, not a panic.

Trait Implementations

impl Clone for WriterHandle

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WriterHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.