Session baggage #

Session baggage is a simple key-value store to store state within a session.

You can update the session baggage cache from any backend service, player client or partner client using the updateSessionBaggageV1 (player sessions) or updateSessionBaggagePartnerV1 (partner sessions) RPCs.

Update session baggage #

This example demonstrates Player session & Game backend, see below for a list of the other available variants.

#include "Services/PragmaSessionService.h"
#include "Services/PragmaSessionServiceRawBase.h"
#include "Dto/PragmaPlayerSessionRpcDto.h"

//...

FPragma_Session_UpdateSessionBaggageV1Request Request;
Request.Data.Add(TEXT("buildId"), TEXT("1.2.3"));
Request.Data.Add(TEXT("region"), TEXT("us-west-2"));

// To update the social-backend cache instead, use SocialUpdateSessionBaggageV1.
Player->Session()->PragmaSessionService().Raw().GameUpdateSessionBaggageV1(Request,
    [](TPragmaResult<FPragma_Session_UpdateSessionBaggageV1Response> Result, const FPragmaMessageMetadata&)
    {
        if (Result.IsFailure())
        {
            // the update failed — session may not exist or entry limits were exceeded
            return;
        }
        // baggage stored; subsequent RPCs on this session include these entries in logs
    });

using Pragma;
using Pragma.Session;

//...

var request = new UpdateSessionBaggageV1Request();
request.Data.Add("buildId", "1.2.3");
request.Data.Add("region", "us-west-2");

// To update the social-backend cache instead, use SocialUpdateSessionBaggageV1.
player.GetService<SessionService>().Raw.GameUpdateSessionBaggageV1(request, (result, metadata) =>
{
    if (result.IsFailure)
    {
        // the update failed — session may not exist or entry limits were exceeded
        return;
    }
    // baggage stored; subsequent RPCs on this session include these entries in logs
});

A backend service targets a player’s session by pragmaId via the SERVICE-typed variant:

import pragma.Fixed128
import pragma.session.PlayerSessionRpc

//...

suspend fun updatePlayerSessionBaggageExample(pragmaId: Fixed128) {
    val baggageData = mapOf(
        "buildId" to "1.2.3",
        "region" to "us-west-2",
    )

    // For partner sessions instead, use PartnerSessionRpc.UpdateSessionBaggageServicePartnerV1Request.
    val request = PlayerSessionRpc.UpdateSessionBaggageServiceV1Request.newBuilder()
        .setPragmaId(pragmaId)
        .putAllData(baggageData)
        .build()

    val result = requestRpcV2(request, PlayerSessionRpc.UpdateSessionBaggageServiceV1Response::parseFrom)
    result.onFailure {
        // the update failed — session may not exist or entry limits were exceeded
    }
    result.onSuccess {
        // baggage stored; subsequent RPCs on this session include these entries in logs
    }
}

import pragma.loadsimulator.ClientWrapper
import pragma.loadsimulator.ICustomStepTracker
import pragma.session.PlayerSessionRpc.UpdateSessionBaggageV1Request
import pragma.session.PlayerSessionRpc.UpdateSessionBaggageV1Response

//...

override suspend fun runStep(players: List<ClientWrapper>, tracker: ICustomStepTracker) {
    val request = UpdateSessionBaggageV1Request.newBuilder()
        .putData("buildId", "1.2.3")
        .putData("region", "us-west-2")
        .build()

    for (player in players) {
        // Swap player.game for player.social to update the social-backend cache instead.
        player.game.sendOrThrow(request, UpdateSessionBaggageV1Response::class, tracker)
    }
}

# To update the social-backend cache instead, use port 11000 with a <player-social-token>.
curl --location 'http://localhost:10000/v1/rpc' \
--write-out '\nHTTP %{http_code}\n' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <player-game-token>' \
--data '{
    "requestId": 1,
    "type": "PlayerSessionRpc.UpdateSessionBaggageV1Request",
    "payload": {
        "data": {
            "buildId": "1.2.3",
            "region": "us-west-2"
        }
    }
}'

RPC variants #

The full set of variants is:

  • Player session: GameUpdateSessionBaggageV1, SocialUpdateSessionBaggageV1
  • Partner session: GameUpdateSessionBaggagePartnerV1, SocialUpdateSessionBaggagePartnerV1
  • Player session: GameUpdateSessionBaggageV1, SocialUpdateSessionBaggageV1
  • Partner session: GameUpdateSessionBaggagePartnerV1, SocialUpdateSessionBaggagePartnerV1
  • Player session: PlayerSessionRpc.UpdateSessionBaggageV1Request
  • Partner session: PartnerSessionRpc.UpdateSessionBaggagePartnerV1Request
  • Service (player session target): PlayerSessionRpc.UpdateSessionBaggageServiceV1Request
  • Service (partner session target): PartnerSessionRpc.UpdateSessionBaggageServicePartnerV1Request
  • Player session: PlayerSessionRpc.UpdateSessionBaggageV1Request
  • Partner session: PartnerSessionRpc.UpdateSessionBaggagePartnerV1Request

DefaultSessionPlugin #

The DefaultSessionPlugin.validateBaggage method merges incoming entries into the existing baggage cache, enforcing per-entry size limits and a total entry cap:

  • Entries whose key or value exceed the configured size limits are dropped and logged as a warning; the rest of the request still applies.
  • If merging the surviving entries would push the total above the entry cap, the operation fails with BaggageEntryLimitExceededApplicationError and the cache is left unchanged.

Configuration (DefaultSessionPluginConfig):

SettingDefaultDescription
baggageEntryLimit5Maximum number of entries stored on a session.
baggageKeySizeLimit36Maximum key length, in characters.
baggageValueSizeLimit36Maximum value length, in characters.

Example config raising the entry cap and value size limit:

game:
  pluginConfigs:
    GamePlayerSessionService.sessionPlugin:
      class: pragma.session.DefaultSessionPlugin
      config:
        baggageEntryLimit: 10
        baggageValueSizeLimit: 128

game:
  pluginConfigs:
    GamePartnerSessionService.sessionPlugin:
      class: pragma.session.DefaultSessionPlugin
      config:
        baggageEntryLimit: 10
        baggageValueSizeLimit: 128

social:
  pluginConfigs:
    SocialPlayerSessionService.sessionPlugin:
      class: pragma.session.DefaultSessionPlugin
      config:
        baggageEntryLimit: 10
        baggageValueSizeLimit: 128

social:
  pluginConfigs:
    SocialPartnerSessionService.sessionPlugin:
      class: pragma.session.DefaultSessionPlugin
      config:
        baggageEntryLimit: 10
        baggageValueSizeLimit: 128
  • Request baggage optionally includes session baggage entries, attaching them to logs and metrics for every RPC handled on the session.

Session
Login