Class GuildRankService

Namespace

FishMMO.Database.Npgsql.Services

Assembly

FishMMO-DB.dll

Base class for database services that execute EF Core operations with consistent execution behavior (transactional and read-only), retry behavior for transient failures, and standardized error mapping into DatabaseResult.

public sealed class GuildRankService : BaseService<GuildRankEntity>, IGuildRankService

Inheritance

object

BaseService<GuildRankEntity>

GuildRankService

Implements

IGuildRankService

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This base type provides three primary execution paths:

• ExecuteTransactionAsync(Func<Task>, CancellationToken) and ExecuteTransactionAsync<TResult>(Func<Task<TResult>>,string,CancellationToken) create a fresh NpgsqlDbContext, begin an explicit transaction, execute the delegate, then call SaveChangesAsync(CancellationToken) and commit.
• ExecuteWriteAsync(Func<Task>,string,CancellationToken) and ExecuteWriteAsync<TResult>(Func<Task<TResult>>,string,CancellationToken) create a fresh NpgsqlDbContext, execute the delegate, then call SaveChangesAsync(CancellationToken) without starting an explicit transaction.
• ExecuteReadAsync(Func<Task>,string,CancellationToken) and ExecuteReadAsync<TResult>(Func<Task<TResult>>,string,CancellationToken) create a fresh NpgsqlDbContext but do not start an explicit transaction and do not call SaveChanges.

Standalone Execution (no ambient scope): A new context is created per attempt to avoid EF change-tracker state leaking across retries. Transient database failures are retried with exponential backoff. Optimistic concurrency conflicts (Version-based authority) and StaleStateException are never retried; they are returned as non-transient failures so the caller can re-read and decide how to proceed.

Ambient Scope Execution (inside an existing Unit of Work): When an operation detects an active FishMMO.Database.Npgsql.Services.DatabaseExecutionScope, it reuses the ambient NpgsqlDbContext and does NOT retry on transient failures. This is by design for the following reasons:

1. Transaction State Corruption: PostgreSQL aborts the entire transaction on most transient failures. The connection and transaction become unusable, making retry with the same context impossible.
2. Context State Pollution: The DbContext's change tracker accumulates state. Retrying with a polluted change tracker can cause duplicate key violations or incorrect updates.
3. Semantic Correctness: If operation A succeeded and operation B failed transiently, retrying B alone without re-evaluating A's preconditions could violate business invariants.

When a transient failure occurs inside an ambient scope, the failure is returned immediately so the caller can restart the entire unit of work with fresh state. Savepoints are used for nested atomicity but cannot recover from connection-level failures.

Constructors

GuildRankService(INpgsqlDbContextFactory)

Initializes a new instance of GuildRankService.

public GuildRankService(INpgsqlDbContextFactory dbContextFactory)

Parameters

dbContextFactory INpgsqlDbContextFactory

DbContext factory for creating contexts.

Methods

DeleteAsync(long, byte, CancellationToken)

Deletes a rank row, refusing while any member still holds it.

public Task<DatabaseResult> DeleteAsync(long guildId, byte rankOrder, CancellationToken cancellationToken = default)

Parameters

guildId long

Guild ID.

rankOrder byte

The rank position to delete.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult>

A result indicating success or failure.

Remarks

The occupancy test and the delete are ONE statement. Split across two round trips, a member could be moved into the rank between them and end up holding a rank that no longer exists — which reads back as no permissions at all, quietly, forever.

EnsureDefaultsAsync(long, IReadOnlyList<GuildRankData>, CancellationToken)

Creates the default rank ladder for a guild if it does not already have one.

public Task<DatabaseResult<int>> EnsureDefaultsAsync(long guildId, IReadOnlyList<GuildRankData> defaults, CancellationToken cancellationToken = default)

Parameters

guildId long

Guild ID.

defaults IReadOnlyList<GuildRankData>

The rows to seed, in any order.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<int>>

The number of rows actually inserted.

Remarks

IDEMPOTENT. Every row is inserted with ON CONFLICT (guild_id, rank_order) DO NOTHING, so running this against a guild that already has ranks changes nothing and returns zero. That is what makes it safe to call on every guild read, which is in turn what makes the migration of existing guilds require no migration step at all: a guild created before rank rows existed grows them the first time anybody looks at it, with the permissions its old enum ranks implied.

FetchManyAsync(long, CancellationToken)

Fetches every rank row for a guild, ordered by rank order ascending.

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

Parameters

guildId long

Guild ID.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult<IReadOnlyList<GuildRankData>>>

The guild's rank ladder.

InsertAsync(GuildRankData, int, byte, CancellationToken)

Inserts a new rank at a position, moving everything already at or above it up one rung.

public Task<DatabaseResult> InsertAsync(GuildRankData rank, int maxRanks, byte maxRankOrder, CancellationToken cancellationToken = default)

Parameters

rank GuildRankData

The rank to insert. Its rank order is the POSITION it takes.

maxRanks int

Maximum rank rows one guild may own.

maxRankOrder byte

Highest legal rank order, which bounds the shift.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult>

A result indicating success or failure.

Remarks

Why this inserts rather than fills a hole. A guild is seeded with three CONTIGUOUS ranks — member 1, officer 2, leader 3 — and a rank may only be created strictly below the creator's own seat. A leader at order 3 therefore has orders 1 and 2 to choose from and both are taken, so a "create at a free position" service could never add a rank to a guild that had not already had one removed. Making room is the operation; finding a gap was never going to find one.

Membership rows move with the ladder. character_guild.rank holds the same order byte, so every member at or above the insertion point is shifted by the same one rung, in the same transaction. Relative standing is what the whole permission model compares, and it is preserved exactly: a member who outranked another before the insert still does, and the leader — defined as the highest order that exists — is still the same character.

The shift is applied one row at a time, highest first. (guild_id, rank_order) is UNIQUE and PostgreSQL checks it per row rather than at statement end, so a single SET rank_order = rank_order + 1 over the whole range raises a duplicate key the moment the planner happens to reach a row whose target is still occupied. Descending, each target has just been vacated. Twelve ranks is the cap, so this is at most eleven statements for something a guild does once in a while.

UpdateAsync(long, byte, string, long, long, CancellationToken)

Updates one rank's name and permission mask.

public Task<DatabaseResult> UpdateAsync(long guildId, byte rankOrder, string name, long permissions, long incomingVersion, CancellationToken cancellationToken = default)

Parameters

guildId long

Guild ID.

rankOrder byte

The rank position to update.

name string

New display name.

permissions long

New permission bit mask.

incomingVersion long

The authoritative, monotonic version for this update.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<DatabaseResult>

A result indicating success or failure.