The Serverless Statelessness Struggle
We love serverless for its scalability, cost-efficiency, and simplified operations. It's fantastic for request/response patterns, event processing, and task automation. However, its inherently stateless nature presents a significant challenge when building applications that require maintaining conversational state, managing ongoing processes, or handling complex, multi-user interactions.
Consider the backend for a multiplayer game. You need to track players in lobbies, manage game turns, update scores in real-time, and handle player disconnections. In a traditional stateless functions model, each incoming request (e.g., 'join lobby', 'make move') is a standalone event. To manage the game's state, you'd constantly be reading from and writing to an external database (like Azure Cosmos DB, SQL Database, or Redis). This approach introduces complexity:
- Increased latency due to frequent database round trips.
- Complex concurrency handling to prevent race conditions when multiple players update the same game state.
- Higher costs from database read/write operations.
- Boilerplate code for state persistence and retrieval in every relevant function.
Imagine a simple online board game. Managing the state of who's in the game, whose turn it is, and the board's current configuration becomes a significant burden, pulling focus away from the core game logic.
The Solution: Embrace State with Azure Durable Entities
Azure Durable Functions extends Azure Functions, bringing stateful capabilities to the serverless world. While Orchestrator functions manage workflow state, Durable Entities provide a way to create small, long-lived, stateful objects – think of them as virtual actors. Each entity has a unique identity and internal state, and they interact with each other and orchestrations through message passing.
For our multiplayer game backend, we can model game components or aspects as entities:
- A
LobbyEntity could manage the list of players waiting for a game.
- A
GameEntity could hold the state for a specific game instance (board state, scores, current player's turn).
- A
PlayerEntity (though less common in simple scenarios) could track a player's overall stats or status.
Let's walk through building a simplified game lobby using a Durable Entity.
Step 1: Define the Entity Interface and Implementation
Entities are typically defined using a class that includes methods representing the operations that can be invoked on the entity. The state is simply class members.
Here's a simplified C# example:
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Newtonsoft.Json;
// Define the state object
[JsonObject(MemberSerialization.OptIn)]
public class LobbyState
{
[JsonProperty("players")]
public List<string> Players { get; set; } = new List<string>();
[JsonProperty("maxPlayers")]
public int MaxPlayers { get; set; } = 4; // Example: Max players
public bool IsFull => Players.Count >= MaxPlayers;
}
// Define the Entity class with operations
public class LobbyEntity
{
[JsonProperty("state")]
public LobbyState State { get; set; }
public LobbyEntity()
{
// Initialize state on first access
State ??= new LobbyState();
}
// Operation to add a player
public void AddPlayer(string playerName)
{
if (!State.Players.Contains(playerName) && !State.IsFull)
{
State.Players.Add(playerName);
Entity.Current.SignalEntity(Entity.Current.EntityKey, "PlayerAdded", playerName); // Optional: Signal self or others
}
}
// Operation to remove a player
public void RemovePlayer(string playerName)
{
if (State.Players.Contains(playerName))
{
State.Players.Remove(playerName);
Entity.Current.SignalEntity(Entity.Current.EntityKey, "PlayerRemoved", playerName); // Optional: Signal self or others
}
}
// Operation to get the current state
public LobbyState Get() => State;
// Operation to reset the lobby
public void Reset() => State = new LobbyState();
// The main dispatcher method
[FunctionName(nameof(LobbyEntity))]
public static Task Run([EntityTrigger] IDurableEntityContext ctx)
{
return ctx.DispatchAsync<LobbyEntity>();
}
}
And here's a Python equivalent:
import azure.functions as func
import azure.durable_functions as df
import json
# Define the state object structure (implicitly handled by Python dict)
# class LobbyState:
# def __init__(self, players=None, max_players=4):
# self.players = players if players is not None else []
# self.max_players = max_players
# @property
# def is_full(self):
# return len(self.players) >= self.max_players
# Define the Entity function
async def lobby_entity(ctx: df.DurableEntityContext):
# Get or initialize state
current_state = ctx.get_state(lambda: {"players": [], "max_players": 4}) # Use dictionary for state
operation = ctx.operation_name
op_input = ctx.get_input()
if operation == "addPlayer":
player_name = op_input
if player_name not in current_state["players"] and len(current_state["players"]) < current_state["max_players"]:
current_state["players"].append(player_name)
# Optional: Signal self or others - requires orchestrator interaction or direct entity calls
# ctx.signal_entity(ctx.entity_key, "playerAdded", player_name)
ctx.set_state(current_state) # Save state
elif operation == "removePlayer":
player_name = op_input
if player_name in current_state["players"]:
current_state["players"].remove(player_name)
# Optional: Signal self or others
# ctx.signal_entity(ctx.entity_key, "playerRemoved", player_name)
ctx.set_state(current_state) # Save state
elif operation == "get":
ctx.return_value(current_state)
elif operation == "reset":
ctx.set_state({"players": [], "max_players": 4})
# No explicit return needed for entity functions that use ctx.set_state() or ctx.return_value()
# Bind the entity function
# Typically, this function is registered in function.json
# {
# "scriptFile": "__init__.py",
# "bindings": [
# {
# "name": "ctx",
# "type": "entityTrigger",
# "direction": "in"
# }
# ]
# }
The [EntityTrigger] binding (or its equivalent in Python) handles receiving signals and orchestrates state persistence behind the scenes using the configured Durable Functions storage provider (often Azure Storage).
Step 2: Interacting with the Entity from an Orchestrator or Client Function
Entities are invoked via signals or calls. Signals are fire-and-forget, while calls wait for the entity operation to complete and potentially return a value.
Example Orchestrator calling the Lobby Entity (C#):
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Extensions.Logging;
public static class GameOrchestrations
{
[FunctionName("CreateAndManageLobby")]
public static async Task RunOrchestrator(
[OrchestrationTrigger] IDurableOrchestrationContext context,
ILogger log)
{
string lobbyId = context.GetInput<string>();
var lobbyEntityId = new EntityId(nameof(LobbyEntity), lobbyId);
log.LogInformation($"Creating or getting lobby entity: {lobbyId}");
// Example: Add players to the lobby
await context.CallEntityAsync(lobbyEntityId, "addPlayer", "Player1");
await context.CallEntityAsync(lobbyEntityId, "addPlayer", "Player2");
// Example: Query the lobby state
LobbyState currentLobbyState = await context.CallEntityAsync<LobbyState>(lobbyEntityId, "get");
log.LogInformation($"Current players in lobby {lobbyId}: {string.Join(", ", currentLobbyState.Players)}");
// You could add logic here to start a game orchestration when the lobby is full
if (currentLobbyState.IsFull)
{
log.LogInformation($"Lobby {lobbyId} is full. Starting game.");
// Start a new game orchestration, passing the player list
await context.CallSubOrchestratorAsync("GameOrchestrator", currentLobbyState.Players);
// Optionally reset the lobby after game start
await context.CallEntityAsync(lobbyEntityId, "reset");
}
// The orchestration can continue managing the lobby or wait for signals
}
}
Example HTTP Trigger client signaling the Lobby Entity (C#):
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Extensions.Logging;
public static class GameApi
{
[FunctionName("JoinLobbyHttp")]
public static async Task<IActionResult> JoinLobby(
[HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "lobby/{lobbyId}/join")] HttpRequestMessage req,
[DurableClient] IDurableEntityClient entityClient,
string lobbyId,
ILogger log)
{
string playerName = await req.Content.ReadAsStringAsync();
var lobbyEntityId = new EntityId(nameof(LobbyEntity), lobbyId);
log.LogInformation($"Player {playerName} attempting to join lobby {lobbyId}");
// Signal the entity to add a player - fire and forget
await entityClient.SignalEntityAsync(lobbyEntityId, "addPlayer", playerName);
return new OkObjectResult($"Signaled lobby {lobbyId} to add player {playerName}.");
}
[FunctionName("GetLobbyStateHttp")]
public static async Task<IActionResult> GetLobbyState(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "lobby/{lobbyId}")] HttpRequestMessage req,
[DurableClient] IDurableEntityClient entityClient,
string lobbyId,
ILogger log)
{
var lobbyEntityId = new EntityId(nameof(LobbyEntity), lobbyId);
log.LogInformation($"Getting state for lobby {lobbyId}");
// Read the entity state directly
var entityStateResponse = await entityClient.ReadEntityStateAsync<LobbyState>(lobbyEntityId);
if (entityStateResponse.EntityExists)
{
return new OkObjectResult(entityStateResponse.EntityState);
}
else
{
return new NotFoundObjectResult($"Lobby entity {lobbyId} not found.");
}
}
}
Note that the HTTP trigger for joining signals the entity (async, fire-and-forget), while the HTTP trigger for getting state calls the entity (sync, waits for state). Orchestrators can only *call* entities; they cannot signal them directly and continue.
Final Step: Azure Portal Configuration
Deploying Durable Entities is the same as deploying any Azure Functions app with the Durable Functions extension. You'll need:
- An Azure Functions app ( Consumption, Premium, or Dedicated plan).
- A Storage Account linked to the Function app (used by Durable Functions for state persistence).
- Ensure the Durable Functions extension is installed (usually included in newer templates, or add via NuGet/PyPI).
No specific portal configuration is needed *for the entities themselves* beyond the standard Function App setup. The magic of state management is handled by the Durable Task Framework runtime leveraging the storage account.
Architecture Diagram
Diagram Summary: Clients interact with HTTP Trigger functions. These triggers use the Durable Functions client bindings to signal or call Durable Entities (like the Lobby Entity) or start Durable Orchestrations (like the Game Orchestrator). Entities manage their own state persisted in Azure Storage. Orchestrators coordinate Activity Functions and interact with Entities to manage the overall game flow and state.
Comparing Alternatives
Using Durable Entities for state management in this scenario offers distinct advantages over traditional stateless functions relying solely on external databases:
- Reduced Complexity: The entity encapsulates state and operations. You don't scatter state management logic across multiple stateless functions.
- Concurrency Handling: Durable Entities automatically handle concurrency for operations invoked on them, preventing race conditions on the entity's state without explicit locking code in your functions. Operations are processed one at a time per entity.
- Simplified Code: Less boilerplate code for fetching, updating, and saving state compared to manual database interactions in every function.
- Actor Model Benefits: Provides a natural way to model independent, stateful components that interact via messages.
Alternatives like using Redis for caching and state or relying heavily on database transactions are possible but often require more manual coding for state consistency, concurrency, and recovery compared to the built-in features of Durable Entities.
