Glossary of Terms

Action

A serverless function that is executed based on a trigger. The trigger could be an HTTP or gRPC request or a stream of messages or events.

CI/CD

You can deploy Services using a Continuous Integration/Continuous Delivery service. See Integrate with CI/CD tools for instructions.

Component

The SDKs support Service Action, Entity, and View components. These components enable you to implement your business logic.

Command

A command comes from a sender, and a reply may be sent to the sender. A command expresses the intention to alter the state of an Entity. A command is materialized by a message received by a Service implementation. Commands may come from outside the Stateful service, perhaps from other stateful services running on Akka Serverless or from external systems, or they may come from within the service, invoked as a side effect or to forward command handling from another command. Commands are not persisted. A command might fail.

Command handler

A command handler is the code that handles a command. It may validate the command using the current state, and may emit events as part of its processing. A command handler must not update the state of the entity directly, only indirectly by emitting events. If a command handler does update the state, then when the entity is passivated (removed from memory), those updates will be lost.

Effect

From a Command handler a Component may notify other components by emitting effects. Effects trigger commands on other components, but do not affect the originating command. (To give a different component the responsibility to reply to the originating command, use a Forward.)

Entity

You implement one or more entities that are bundled into a Service implementation. An entity is conceptually equivalent to a class, or a type of state. An entity will have multiple Entity instances, each of which has a unique ID and can handle commands. For example, a service may implement a chat room entity, encompassing the logic associated with chat rooms, and a particular chat room may be an instance of that entity, containing a list of the users currently in the room and a history of the messages sent to it. Entities cache their state and persist it using Events.

Entity instance

An instance of an Entity, which is identified by a unique Entity key. An entity holds state in the Service implementation, and this state is held within the context of a gRPC stream.

Entity key

A key used to identify instances of an Entity. All Commands must contain the entity key so that the command can be routed to the right instance of the entity that the command is for. The gRPC descriptor annotates the incoming message types for the entity to indicate which field(s) contain the entity key.

Entity type

The type of state management that an Entity uses. Available types include Event Sourced Entity and Value Entity. Each type has its own sub protocol that it uses for state management, to convey state and updates specific to that type.

Event

An event indicates that a change has occurred to an entity and persists the current state. Events are stored in a journal, and are read and replayed each time the entity is reloaded by the Akka Serverless state management system. An event emitted by one service might be interpreted as a command by another.

Event handler

An event handler is the only piece of code that is allowed to update the state of the entity. It receives events, and, according to the event, updates the state.

Event Sourced Entity

A type of Entity that stores its state using a journal of events, and restores its state by replaying that journal. These are discussed in more detail in Event Sourced state model.

Forward

A Component's Command handler may forward command processing to another component by issueing a forward. The target component’s reply will become the originating commands reply.

gRPC

A Remote Procedure Call framework developed by Google that provides high-performance communication between services. By default, gRPC uses Protocol Buffers (or Protobuf for short) for language-neutral serialization. As a developer, you write one file (.proto) that specifies the contract of your service containing the input, output, and operations. External consumers will use the contract to know how to call your service.

Journal

Persistent storage for Events from Event Sourced Entitys. Some documentation uses the terms Event Log or Event Store instead of journal. Akka Serverless handles event storage for you, relieving you of connecting to, configuring, or managing the journal.

Proxy

When you deploy a Service, Akka Serverless deploys a proxy along with it. The proxy manages entity state, and exposes the service implementation to the rest of the system. It translates incoming messages to commands and sends them to the service. The proxy also forms an Akka cluster with other nodes of the same stateful service, allowing advanced distributed state management features such as sharding, replication and addressed communication between nodes.

Service

A service is implemented by an Akka Serverless SDK. At runtime, Akka Serverless enriches the incoming and outgoing gRPC messages with state management capabilities, such as the ability to receive and update state. You implement the business logic for the service, which includes stateful entities. You deploy your services to Akka Serverless and Akka Serverless adds a Proxy that handles incoming communication and persistence at runtime.

Service implementation

A service implementation includes the logic that you write for stateful entities. You package a service as a Docker image, and Akka Serverless deploys it as a Stateful service.

Snapshot

A snapshot records current state of an Event Sourced Entity. Akka Serverless persists snapshots periodically as an optimization. With snapshots, when the Entity is reloaded from the journal, the entire journal doesn’t need to be replayed, just the changes since the last snapshot.

State

The state is simply data—​the current set of values for an entity instance. Event Sourced Entities hold their state in memory.

State model

Each entity uses one of the supported state models. The state model determines the way Akka Serverless manages data. Currently, these include Value Entity and Event Sourced Entity.

Stateful service

A stateful service is a deployable unit. It is represented in Kubernetes as a StatefulService resource. It contains a Service implementation and a Proxy. The Akka Serverless operator transforms a stateful service into a Kubernetes Deployment resource and defines a Kubernetes Service to expose the stateful service to the outside world.

Stateful store

A stateful store is an abstraction over a datastore, typically a database. It is represented in Kubernetes as a StatefulStore resource. Akka Serverless manages the stateful store for you.

Value Entity

A Value Entity stores state in an update-in-place model, similar to a Key-Value store that supports CRUD (Create, Read, Update, Delete) operations. In Domain Driven Design (DDD) terms, a Value Entity is an "Entity". In contrast with "Value Objects", you reference Entities by an identifier and the value associated with that identifier can change (be updated) over time.

View

A View provides a way to retrieve state from multiple Entities based on a query. You can query non-key data items. You can create views from Value Entity state, Event Sourced Entity events, and by subscribing to topics.