Interface IPartyUpdateService

Namespace

FishMMO.Database.Npgsql.Services.Interfaces

Assembly

FishMMO-DB.dll

Service interface for party update timestamp tracking. Provides async methods for persisting, deleting, and fetching party update records.

public interface IPartyUpdateService

Remarks

Write operations (Persist*, Delete*) are executed through BaseService<TEntity> wrappers, which provide consistent retry and error mapping behavior for transient database failures.

All methods return DatabaseResult or DatabaseResult<T> to provide structured error information through the DatabaseException system, helping distinguish between: - Validation failures (invalid parameters) - Not found scenarios (party doesn't exist) - Database errors (connection issues, constraint violations, timeouts) - Entity not found errors - Unexpected runtime errors

PersistAsync uses a single-statement UPSERT to prevent race conditions during concurrent updates.

Methods

DeleteAsync(long, CancellationToken)

Deletes all update records for a party.

Task<DatabaseResult<int>> DeleteAsync(long partyId, CancellationToken cancellationToken = default)

Parameters

partyId long

Party ID.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<int>>

A DatabaseResult<T> containing the number of records deleted on success, or a DatabaseException on failure.

Remarks

This is an idempotent cleanup operation. Unlike entity delete methods, this method does NOT throw DatabaseEntityNotFoundException when no records exist. Instead, it returns 0 rows deleted. This design supports safe concurrent cleanup where multiple callers may attempt to delete the same records.

Uses a single-statement DELETE.

FetchAsync(List<long>, DateTime, CancellationToken)

Fetches party update records for specified parties updated since last fetch.

Task<DatabaseResult<List<PartyUpdateData>>> FetchAsync(List<long> partyIds, DateTime lastFetch, CancellationToken cancellationToken = default)

Parameters

partyIds List<long>

List of party IDs to check.

lastFetch DateTime

Timestamp to compare against.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<List<PartyUpdateData>>>

A DatabaseResult<T> containing the list of party update data on success, or a DatabaseException on failure.

Remarks

Filters by both timestamp and party ID list.

PersistAsync(long, CancellationToken)

Saves or updates the last update timestamp for a party using atomic UPSERT.

Task<DatabaseResult> PersistAsync(long partyId, CancellationToken cancellationToken = default)

Parameters

partyId long

Party ID.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult>

A DatabaseResult indicating success or containing a DatabaseException on failure.

Remarks

Uses a single-statement PostgreSQL INSERT ... ON CONFLICT DO UPDATE with a conditional update to avoid regressing last_update.