Class CharacterGuildService

Namespace

FishMMO.Database.Npgsql.Services

Assembly

FishMMO-DB.dll

Service for managing character guild membership in the database. Provides async operations for CRUD operations on character guild membership data. Implements execution strategies for automatic retry on transient database failures. Returns DatabaseResult for consistent, safe error handling.

public sealed class CharacterGuildService : BaseService<CharacterGuildEntity>, ICharacterGuildService, ICountByKeyAction<long>, IDeleteByKeyVersionedAction<long>, IFetchByKeyAction<long, CharacterGuildData?>, IFetchManyByKeyAction<long, CharacterGuildData>

Inheritance

object

BaseService<CharacterGuildEntity>

CharacterGuildService

Implements

ICharacterGuildService

ICountByKeyAction<long>

IDeleteByKeyVersionedAction<long>

IFetchByKeyAction<long, CharacterGuildData?>

IFetchManyByKeyAction<long, CharacterGuildData>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This service manages character guild membership including:

• Guild membership save/update with atomic UPSERT operations
• Rank updates
• Membership deletion
• Membership retrieval (individual and guild-wide)
• Member count queries

All exceptions are classified by BaseService and mapped to DatabaseResult error codes (e.g., UNIQUE_VIOLATION, FOREIGN_KEY_VIOLATION, STALE_STATE, DATABASE_ERROR). Transient failures are retried automatically. Methods return DatabaseResult to provide structured error handling without throwing exceptions to calling code.

Constructors

CharacterGuildService(INpgsqlDbContextFactory)

Initializes a new instance of the CharacterGuildService class.

public CharacterGuildService(INpgsqlDbContextFactory dbContextFactory)

Parameters

dbContextFactory INpgsqlDbContextFactory

Factory for creating database contexts.

Exceptions

ArgumentNullException

Thrown when dbContextFactory is null.

Methods

CountAsync(long, CancellationToken)

Counts items for the given key.

public Task<DatabaseResult<int>> CountAsync(long guildId, CancellationToken cancellationToken = default)

Parameters

guildId long

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult<int>>

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 an entity for the given key.

public Task<DatabaseResult<CharacterGuildData?>> FetchAsync(long characterId, CancellationToken cancellationToken = default)

Parameters

characterId long

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult<CharacterGuildData?>>

FetchManyAsync(long, CancellationToken)

Fetches many items for the given key.

public Task<DatabaseResult<IReadOnlyList<CharacterGuildData>>> FetchManyAsync(long guildId, CancellationToken cancellationToken = default)

Parameters

guildId long

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult<IReadOnlyList<CharacterGuildData>>>

PersistAsync(CharacterGuildData, int, CancellationToken)

Persists the provided guild membership data, enforcing capacity limits.

public Task<DatabaseResult> PersistAsync(CharacterGuildData guildData, int maxCapacity, CancellationToken cancellationToken = default)

Parameters

guildData CharacterGuildData

The guild membership data to persist.

maxCapacity int

The maximum number of members allowed in the guild.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult>

A DatabaseResult indicating success or failure.

UpdateNoteAsync(long, long, string, bool, CancellationToken)

Writes one of a member's two guild notes.

public Task<DatabaseResult> UpdateNoteAsync(long characterId, long guildId, string note, bool isOfficerNote, CancellationToken cancellationToken = default)

Parameters

characterId long

The member the note is about.

guildId long

The guild the note belongs to.

note string

The note text. Capped at 128 characters.

isOfficerNote bool

True for the officer-only note, false for the public one.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult>

A DatabaseResult indicating success or failure.

Remarks

The guild is in the WHERE clause. A note request naming a character who has since left — or who was never in the editor's guild — must not write, and this is where that is guaranteed rather than merely checked earlier.

UpdateRankAsync(long, long, byte, long, CancellationToken)

Updates a character's guild rank if incomingVersion is newer.

public Task<DatabaseResult> UpdateRankAsync(long characterId, long guildId, byte rank, long incomingVersion, CancellationToken cancellationToken = default)

Parameters

characterId long

The character ID.

guildId long

The guild ID.

rank byte

The new rank.

incomingVersion long

The authoritative, monotonic version for this update operation.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult>

A DatabaseResult indicating success or failure.