Interface IChatService

Namespace

FishMMO.Database.Npgsql.Services.Interfaces

Assembly

FishMMO-DB.dll

Service interface for chat message operations. Provides async methods for persisting and fetching chat messages.

public interface IChatService

Remarks

Write operations (Persist*) 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 retry handling is done by BaseService, not by provider-level retry. BaseService uses explicit transactions only when a write requires multiple database statements. This interface describes behavior; the implementation uses BaseService execution wrappers.

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

Methods

FetchAsync(DateTime, long, int, long, CancellationToken)

Fetches paginated chat messages excluding local messages for the specified scene server.

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

Parameters

lastFetch DateTime

Timestamp to compare messages against.

lastPosition long

Last message ID fetched (for pagination).

amount int

Maximum number of messages to fetch.

sceneServerId long

Scene server ID to filter out local messages.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<List<ChatData>>>

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

Remarks

This method uses LINQ with AsNoTracking for optimal read performance and automatically benefits from the retry policy configured on the DbContext without requiring explicit execution strategy wrapping. Filters out local channel messages (Tell, Guild, Party, World, Trade) from the specified scene server. Returns empty list for invalid amount.

PersistAsync(long, string, string, long, long, ChatChannel, string, DateTime, CancellationToken)

Persists a chat message with denormalized audit fields.

Task<DatabaseResult> PersistAsync(long characterId, string characterName, string accountName, long worldServerId, long sceneServerId, ChatChannel channel, string message, DateTime serverReceivedTime, CancellationToken cancellationToken = default)

Parameters

characterId long

Character ID sending the message.

characterName string

Character name (denormalized for audit retention).

accountName string

Account name (denormalized for audit retention).

worldServerId long

World server ID.

sceneServerId long

Scene server ID.

channel ChatChannel

Chat channel.

message string

Message content.

serverReceivedTime DateTime

Timestamp when server received the message (for legal audit trail).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult>

A DatabaseResult indicating success or containing a DatabaseException on failure.

Remarks

Chat audit fields are denormalized so logs can survive character deletion. Passing the names avoids a race where the character row is deleted between lookup and insert. Uses BaseService.ExecuteWriteAsync for:

• Automatic transient failure retry
• Centralized exception handling and mapping
• Consistent DatabaseResult pattern

PersistBatchAsync(List<(long characterId, string characterName, string accountName, long worldServerId, long sceneServerId, ChatChannel channel, string message, DateTime serverReceivedTime)>, int, CancellationToken)

Persists multiple chat messages in batches.

Task<DatabaseResult> PersistBatchAsync(List<(long characterId, string characterName, string accountName, long worldServerId, long sceneServerId, ChatChannel channel, string message, DateTime serverReceivedTime)> messages, int maxBatchSize = 1000, CancellationToken cancellationToken = default)

Parameters

messages List<(long characterId, string characterName, string accountName, long worldServerId, long sceneServerId, ChatChannel channel, string message, DateTime serverReceivedTime)>

List of chat messages to persist. Each tuple contains: (characterId, characterName, accountName, worldServerId, sceneServerId, channel, message, serverReceivedTime).

maxBatchSize int

Maximum number of messages per database round-trip (500–2500).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult>

A DatabaseResult indicating success or failure.