Skip to content

bruce48x/Lakona / skills/lakona-implement-session-lifecycle

lakona-implement-session-lifecycle

Verified

Implement or update Lakona Game Session lifecycle policy in Server.Hotfix using IGameSessionLifecycle. Use when handling disconnect, resume-window retention, expiration, application-defined session ownership, stale lifecycle events, presence or room cleanup, or fixing Hotfix lifecycle binding and tests.

FileKindSize
SKILL.mdskill md7.8 KB
agents/openai.yamlconfig258 B
references/session-lifecycle-shapes.mdmarkdown6.6 KB

references/session-lifecycle-shapes.md

View on GitHub
# Lakona Session Lifecycle Shapes

Use the installed Lakona version and neighboring project code as the API authority. The examples below describe current concepts and safety invariants, not a namespace template.

## Vocabulary

| Concept | Lifetime | Owner |
| --- | --- | --- |
| RPC Session | One live transport connection | RPC runtime |
| Game Session | Resumable server session across connections | Lakona Game Server |
| Player Session | Product login or character presence | Game domain |

Do not infer that these lifetimes begin or end together.

## Lifecycle Binding

```csharp
[HotfixLifecycle]
public sealed class GameSessionLifecycle : IGameSessionLifecycle
{
    public ValueTask SessionDisconnectedAsync(
        HotfixLifecycleCall<GameSessionDisconnectedRequest> call)
    {
        // Retain resumable domain state unless product policy says otherwise.
        return default;
    }

    public ValueTask SessionResumedAsync(
        HotfixLifecycleCall<GameSessionResumedRequest> call)
    {
        // Restore matching product presence after recovery replay.
        return default;
    }

    public ValueTask SessionExpiredAsync(
        HotfixLifecycleCall<GameSessionExpiredRequest> call)
    {
        // Perform product cleanup through the business owner.
        return default;
    }
}
```

Select the handler when creating the session:

```csharp
var session = await gameServer.StartSessionAsync<GameSessionLifecycle>(
    ownerKey, connectionId, cancellationToken);
```

Multiple handler classes are allowed. Non-generic `StartSessionAsync` selects no business lifecycle handler. Recovery retains the selection; callbacks resolve it in the active Hotfix generation. Do not remove or rename a handler while live sessions or pending expiration callbacks reference it: publication rejects that change. Handler instances may serve multiple sessions concurrently, so keep session state in its business owner.

The call exposes only `Request`, identifying framework state through `OwnerKey`, `SessionId`, and `ConnectionId`. It has no item snapshot, cancellation token, or service-provider properties. Constructor-inject dependencies and resolve product ownership through established actor keys or application services.

## Default Policy Matrix

| Event | Framework meaning | Typical product action |
| --- | --- | --- |
| Disconnected | Connection lost; Game Session retained | Keep room and actor state; optionally mark a temporary connection condition |
| Resumed | Replacement connection's recovery heartbeat completed the replay send step | Restore matching presence without recreating durable identity |
| Expired | Recovery window ended; framework session removed | Clear matching session ownership and leave rooms, matchmaking, or presence as product policy requires |
| Explicit termination | Product or administrator ends a session | Call `ILakonaGameServer.TerminateSessionAsync`; the framework handles the termination notice |

`SessionResumedAsync` runs once per committed replacement binding, independently of reliable push being enabled. Initial login, failed recovery, and repeated heartbeats do not trigger it. Replay completion does not mean the client acknowledged every message. Explicit termination does not invoke `SessionExpiredAsync`.

The project may choose a different visible-presence policy, but it must state and test that choice. Avoid presence flicker by default when short disconnects are recoverable.

## Stale-Event Protection

A lifecycle event can race with reconnection or replacement. Before clearing domain state:

1. Resolve the stable business actor from `OwnerKey` or the project's established mapping.
2. Read its current framework-session ownership and any application-defined
   session mapping relevant to the event.
3. Compare the event `SessionId` with the specific current ownership slot.
4. Mutate only the matching slot and its dependent state.
5. Return successfully without mutation when the event is stale or already handled.

Conceptually:

```csharp
var snapshot = await userActor.GetSessionSnapshotAsync(cancellationToken);

if (snapshot.CurrentSessionId == call.Request.SessionId)
{
    await userActor.ClearSessionAsync(call.Request.SessionId, cancellationToken);
}
```

Use the project's generated actor calls and actual key types. Pass the expected session ID into the mutation when possible so the actor enforces the compare-and-clear invariant atomically.

## Application-Defined Session Roles

Lakona does not define control, realtime, lobby, gameplay, or similar Session
types. A product may assign traffic roles to separate Game Sessions, but those
roles belong to application state and policy. When such mappings exist:

- discover the project's actual role vocabulary and ownership mapping
- compare and clear only the slot targeted by the lifecycle event
- keep independently resumable Game Sessions independent by default
- require explicit product policy and tests for cross-termination or shared cleanup

## Explicit Termination

Use the stable server API when the product intentionally terminates a Game Session:

```csharp
await gameServer.TerminateSessionAsync(
    sessionKey,
    SessionTerminationReason.Policy,
    cancellationToken: cancellationToken);
```

Use the product-appropriate `SessionTerminationReason` from `Lakona.Game.Abstractions`.
The framework sends the termination notice through its own notification channel;
application code does not need to send it or bind a business callback for it.
The notice is best-effort and must not become the durable authority for
termination. Do not call lifecycle handlers directly and do not treat a raw
connection close as equivalent.

## State, Cancellation, And Failures

- Use session items only for small scalar values supported by the current API, such as strings, integers, and booleans.
- Lifecycle calls carry only the event request; they do not expose session items.
- Use actors or application services to serialize ownership changes; keep
  business state which must survive process loss in an application Store.
- Cleanup that must survive request cancellation may deliberately use `CancellationToken.None` when established project policy requires it.
- Do not swallow `OperationCanceledException` accidentally or convert concrete cleanup failures into silent success.
- Make repeated expiration and missing-state paths safe and observable according to repository conventions.
- Callback failures are logged and contained without automatic retry or recovery rollback. Use an application-owned durable mechanism for cleanup that must survive callback failure or process loss.

Validate failure paths as well as the happy path: unavailable actor, already-left room, partial cleanup, repeated event, and stale replacement event.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall