Class CharacterBuffService

Namespace

FishMMO.Database.Npgsql.Services

Assembly

FishMMO-DB.dll

Character buff service with async operations, atomic SQL, and DTO pattern. Uses repository pattern with EF Core and raw SQL for race-condition-prone operations. Implements execution strategies for automatic retry on transient database failures. Returns DatabaseResult for consistent, safe error handling with sanitized messages. Follows SOLID principles: SRP, OCP, LSP, ISP, DIP.

public sealed class CharacterBuffService : BaseService<CharacterBuffEntity>, ICharacterBuffService, IPersistManyAction<CharacterBuffData>, IDeleteByKeyVersionedAction<long>, IFetchCollectionByKeyAction<long, CharacterBuffData>

Inheritance

object

BaseService<CharacterBuffEntity>

CharacterBuffService

Implements

ICharacterBuffService

IPersistManyAction<CharacterBuffData>

IDeleteByKeyVersionedAction<long>

IFetchCollectionByKeyAction<long, CharacterBuffData>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

All methods that use ExecuteSqlRawAsync are wrapped in execution strategies to provide automatic retry logic (up to 3 attempts) for transient database failures such as connection timeouts, deadlocks, or network interruptions.

Exception Handling Strategy:

• Catches specific exceptions (NpgsqlException, DbUpdateException, TimeoutException)
• Converts to custom DatabaseException hierarchy with sanitized messages
• Returns DatabaseResult for safe, typed error handling
• Preserves detailed error information for logging while exposing safe messages to clients

Constructors

CharacterBuffService(INpgsqlDbContextFactory)

Initializes a new instance of the CharacterBuffService class.

public CharacterBuffService(INpgsqlDbContextFactory dbContextFactory)

Parameters

dbContextFactory INpgsqlDbContextFactory

Factory for creating database contexts.

Exceptions

ArgumentNullException

Thrown when dbContextFactory is null.

Methods

DeleteAsync(long, long, CancellationToken)

Deletes the entity identified by the given key if incomingVersion is newer.

public Task<DatabaseResult> DeleteAsync(long characterId, long incomingVersion, CancellationToken cancellationToken = default)

Parameters

characterId long

incomingVersion long

The authoritative, monotonic version for this delete operation.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult>

FetchAsync(long, CancellationToken)

Fetches a collection of items for the given key.

public Task<DatabaseResult<IReadOnlyList<CharacterBuffData>>> FetchAsync(long characterId, CancellationToken cancellationToken = default)

Parameters

characterId long

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult<IReadOnlyList<CharacterBuffData>>>

PersistAsync(IEnumerable<CharacterBuffData>, CancellationToken)

Persists the provided items.

public Task<DatabaseResult<BulkWriteResult>> PersistAsync(IEnumerable<CharacterBuffData> buffs, CancellationToken cancellationToken = default)

Parameters

buffs IEnumerable<CharacterBuffData>

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult<BulkWriteResult>>

What the write actually did, or a failure.

Remarks

A successful result does not mean every supplied row was written. Batched writes are version-gated and the service filters what it cannot act on, so the outcome carries counts rather than a bare boolean — see BulkWriteResult, which explains which discrepancies a caller should care about and which are routine.