Interface IKickRequestService

Namespace

FishMMO.Database.Npgsql.Services.Interfaces

Assembly

FishMMO-DB.dll

Service interface for kick request operations. Provides async methods for persisting, deleting, and fetching kick requests.

public interface IKickRequestService

Remarks

Write operations (Persist*, Delete*) in this service use execution strategies to ensure transient database failures are automatically retried according to the retry policy configured on the DbContext. This is critical because SaveChangesAsync and ExecuteSqlRawAsync do not automatically retry on transient failures without an execution strategy wrapper. BaseService provides execution wrappers for retry and centralized exception mapping; explicit transactions are used only when a write requires multiple database statements.

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

Kick requests are used to forcefully disconnect accounts from active sessions.

Methods

DeleteAsync(string, CancellationToken)

Deletes all kick requests for the specified account.

Task<DatabaseResult<int>> DeleteAsync(string accountName, CancellationToken cancellationToken = default)

Parameters

accountName string

Account name whose kick requests will be deleted.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<int>>

A DatabaseResult<T> containing the number of kick requests 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 ExecuteSqlRawAsync with execution strategy wrapping to ensure transient database failures are automatically retried.

FetchAsync(DateTime, long, int, CancellationToken)

Fetches paginated kick requests based on timestamp and position.

Task<DatabaseResult<List<KickRequestData>>> FetchAsync(DateTime lastFetch, long lastPosition, int amount, CancellationToken cancellationToken = default)

Parameters

lastFetch DateTime

Timestamp to compare requests against.

lastPosition long

Last request ID fetched (for pagination).

amount int

Maximum number of requests to fetch.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<List<KickRequestData>>>

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

Remarks

This method uses LINQ (ToListAsync with AsNoTracking) and automatically benefits from the retry policy configured on the DbContext without requiring explicit execution strategy wrapping. Uses pagination pattern with timestamp and ID for reliable cursor-based pagination. Returns empty list for invalid amount.

HasPendingAsync(string, CancellationToken)

Checks whether a pending kick request exists for the specified account.

Task<DatabaseResult<bool>> HasPendingAsync(string accountName, CancellationToken cancellationToken = default)

Parameters

accountName string

Account name to check.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<bool>>

A DatabaseResult<T> containing true if a pending kick request exists, false otherwise, or a DatabaseException on failure.

PersistAsync(string, CancellationToken)

Persists a kick request for the specified account.

Task<DatabaseResult> PersistAsync(string accountName, CancellationToken cancellationToken = default)

Parameters

accountName string

Account name to kick.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult>

A DatabaseResult indicating success or containing a DatabaseException on failure.

Remarks

Uses SaveChangesAsync with execution strategy wrapping to ensure transient database failures are automatically retried. Creates new kick request with current UTC timestamp.