Use a Contract Fist approach to define Actors

.github/workflows/ci.yaml

@@ -32,6 +32,9 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
+      - name: Install Protoc
+        uses: arduino/setup-protoc@v3
+
       - name: Set up Elixir
         uses: erlef/setup-beam@v1
         with:

Makefile

@@ -155,7 +155,7 @@ run-proxy-local2:
 	ERL_ZFLAGS='-proto_dist inet_tls -ssl_dist_optfile rel/overlays/local-mtls.ssl.conf' cd spawn_proxy/proxy && mix deps.get && PROXY_DATABASE_TYPE=$(database) PROXY_HTTP_PORT=9003 SPAWN_STATESTORE_KEY=3Jnb0hZiHIzHTOih7t2cTEPEpY98Tu1wvQkPfq/XwqE= iex --name spawn_a2@test.default.svc -S mix
 
 run-proxy-local-3:
-	cd spawn_proxy/proxy && mix deps.get && SPAWN_PROXY_LOGGER_LEVEL=info PROXY_CLUSTER_STRATEGY=epmd SPAWN_USE_INTERNAL_NATS=true SPAWN_PUBSUB_ADAPTER=nats PROXY_DATABASE_PORT=3307 PROXY_DATABASE_TYPE=mariadb PROXY_DATABASE_POOL_SIZE=30 PROXY_HTTP_PORT=9003 USER_FUNCTION_PORT=8091 SPAWN_STATESTORE_KEY=3Jnb0hZiHIzHTOih7t2cTEPEpY98Tu1wvQkPfq/XwqE= iex --name spawn_a3@127.0.0.1 -S mix
+	cd spawn_proxy/proxy && mix deps.get && SPAWN_PROXY_LOGGER_LEVEL=info PROXY_CLUSTER_STRATEGY=epmd SPAWN_USE_INTERNAL_NATS=false SPAWN_PUBSUB_ADAPTER=nats PROXY_DATABASE_PORT=3307 PROXY_DATABASE_TYPE=mariadb PROXY_DATABASE_POOL_SIZE=30 PROXY_HTTP_PORT=9003 USER_FUNCTION_PORT=8091 SPAWN_STATESTORE_KEY=3Jnb0hZiHIzHTOih7t2cTEPEpY98Tu1wvQkPfq/XwqE= iex --name spawn_a3@127.0.0.1 -S mix
 
 run-proxy-local-nodejs-test:
 	ERL_ZFLAGS='-proto_dist inet_tls -ssl_dist_optfile rel/overlays/local-mtls.ssl.conf' cd spawn_proxy/proxy && mix deps.get && PROXY_DATABASE_TYPE=$(database) PROXY_HTTP_PORT=9001 SPAWN_STATESTORE_KEY=3Jnb0hZiHIzHTOih7t2cTEPEpY98Tu1wvQkPfq/XwqE= PROXY_ACTOR_SYSTEM_NAME=SpawnSysTest SPAWN_SUPERVISORS_STATE_HANDOFF_CONTROLLER=crdt iex --name spawn_a1@test.default.svc -S mix

compile-pb.sh

@@ -4,9 +4,51 @@ set -o nounset
 set -o errexit
 set -o pipefail
 
-protoc --elixir_out=gen_descriptors=true:./lib/spawn/google/protobuf --proto_path=priv/protos/google/protobuf priv/protos/google/protobuf/any.proto
-protoc --elixir_out=gen_descriptors=true:./lib/spawn/actors --proto_path=priv/protos priv/protos/eigr/functions/protocol/actors/actor.proto
-protoc --elixir_out=gen_descriptors=true:./lib/spawn/actors --proto_path=priv/protos priv/protos/eigr/functions/protocol/actors/protocol.proto
-protoc --elixir_out=gen_descriptors=true:./lib/spawn/actors --proto_path=priv/protos priv/protos/eigr/functions/protocol/actors/state.proto
+protoc --elixir_out=gen_descriptors=true,plugins=grpc:./lib/spawn/grpc --proto_path=priv/protos/grpc/ priv/protos/grpc/reflection/v1alpha/reflection.proto
 
-#protoc --elixir_out=gen_descriptors=true:./lib/spawn/cloudevents --proto_path=priv/protos/io/cloudevents/v1 priv/protos/io/cloudevents/v1/spec.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/google/protobuf --proto_path=priv/protos/google/protobuf priv/protos/google/protobuf/any.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/google/protobuf --proto_path=priv/protos/google/protobuf priv/protos/google/protobuf/empty.proto
+# protoc --elixir_out=./lib/spawn/google/protobuf --proto_path=priv/protos/google/protobuf priv/protos/google/protobuf/descriptor.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/google/protobuf --proto_path=priv/protos/google/protobuf priv/protos/google/protobuf/duration.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/google/protobuf --proto_path=priv/protos/google/protobuf priv/protos/google/protobuf/timestamp.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/google/protobuf --proto_path=priv/protos/google/protobuf priv/protos/google/protobuf/struct.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/google/protobuf --proto_path=priv/protos/google/protobuf priv/protos/google/protobuf/source_context.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/google/protobuf --proto_path=priv/protos/google/protobuf priv/protos/google/protobuf/field_mask.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/google/protobuf --proto_path=priv/protos/google/protobuf priv/protos/google/protobuf/wrappers.proto
+
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/actors --proto_path=priv/protos priv/protos/eigr/functions/protocol/actors/extensions.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/actors --proto_path=priv/protos priv/protos/eigr/functions/protocol/actors/actor.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/actors --proto_path=priv/protos priv/protos/eigr/functions/protocol/actors/protocol.proto
+# protoc --elixir_out=gen_descriptors=true:./lib/spawn/actors --proto_path=priv/protos priv/protos/eigr/functions/protocol/actors/state.proto
+
+
+#protoc --elixir_out=gen_descriptors=true:./lib/spawn/actors --proto_path=priv/protos priv/protos/eigr/functions/protocol/actors/healthcheck.proto
+
+#protoc --elixir_out=gen_descriptors=true:./lib/spawn/cloudevents --proto_path=priv/protos/io/cloudevents/v1 priv/protos/io/cloudevents/v1/spec.proto
+
+PROTOS=("
+    priv/protos/eigr/functions/protocol/actors/extensions.proto 
+    priv/protos/eigr/functions/protocol/actors/actor.proto 
+    priv/protos/eigr/functions/protocol/actors/protocol.proto 
+    priv/protos/eigr/functions/protocol/actors/state.proto 
+    priv/protos/eigr/functions/protocol/actors/healthcheck.proto
+")
+
+BASE_PATH=`pwd`
+
+echo "Base protobuf path is: $BASE_PATH/priv/protos"
+
+for file in $PROTOS; do
+  echo "Compiling file $BASE_PATH/$file..."
+
+  mix protobuf.generate \
+    --output-path=./lib/spawn/actors \
+    --include-docs=true \
+    --generate-descriptors=true \
+    --include-path=$BASE_PATH/priv/protos/ \
+    --include-path=./priv/protos/google/protobuf \
+    --include-path=./priv/protos/google/api \
+    --plugins=ProtobufGenerate.Plugins.GRPCWithOptions \
+    --one-file-per-module \
+    $BASE_PATH/$file
+done

config/config.exs

@@ -19,9 +19,8 @@ config :do_it, DoIt.Commfig,
 
 config :logger,
   backends: [:console],
-  truncate: 65536
-
-# level: :info
+  truncate: 65536,
+  level: :debug
 
 #  compile_time_purge_matching: [
 #    [level_lower_than: :info]

config/runtime.exs

@@ -2,5 +2,5 @@ import Config
 
 if config_env() == :prod do
   config :logger,
-    level: String.to_atom(System.get_env("SPAWN_PROXY_LOGGER_LEVEL", "debug"))
+    level: String.to_atom(System.get_env("SPAWN_PROXY_LOGGER_LEVEL", "info"))
 end

docs/modeling_with_actors.md

@@ -1,2 +1,113 @@
 # Modeling Systems with Actors
-TODO
+
+The Actor Model, introduced by Carl Hewitt in 1973, is a conceptual framework for dealing with concurrent computation. Unlike traditional models that rely on shared state and locks, the Actor Model provides a highly modular and scalable approach to designing systems, making it particularly well-suited for distributed and concurrent applications.
+
+At its core, the Actor Model revolves around the concept of "actors"—independent entities that encapsulate state and behavior. Each actor can:
+1. Receive messages from other actors.
+2. Process these messages using its internal behavior.
+3. Send messages to other actors.
+4. Create new actors.
+
+This model inherently avoids issues like race conditions and deadlocks by ensuring that each actor processes only one message at a time. Consequently, the state is modified in a thread-safe manner, as actors do not share state directly but communicate exclusively through message passing.
+
+### Key Benefits
+
+1. **Concurrency and Scalability**: Since actors operate independently, systems based on the Actor Model can easily scale across multiple processors or machines. This makes it ideal for cloud-native applications and services that demand high concurrency.
+
+2. **Fault Tolerance**: Actors can be designed to monitor and manage other actors, allowing for robust error handling and recovery strategies. This self-healing capability is a cornerstone of resilient system design.
+
+3. **Modularity**: Actors encapsulate state and behavior, promoting a modular structure that is easier to reason about, test, and maintain. This separation of concerns aligns well with microservices architecture, where each service can be seen as an actor.
+
+### Using the Actor Model to Build Business Applications
+
+In the realm of business applications, the Actor Model can be employed to create robust, scalable, and maintainable systems. Here’s how it can be leveraged:
+
+1. **Order Processing Systems**: In e-commerce platforms, each order can be represented as an actor. The order actor can handle various stages of the order lifecycle, including validation, payment processing, inventory adjustment, and shipping. By encapsulating these processes within an actor, the system can handle a large number of orders concurrently without interference.
+
+2. **Customer Service Applications**: Each customer session can be modeled as an actor, managing individual interactions and maintaining state throughout the session. This is particularly useful in chatbots and automated customer service systems where maintaining context and state consistency is crucial.
+
+3. **Financial Systems**: In banking applications, transactions can be modeled as actors. This allows for secure, concurrent processing of transactions, ensuring that the system can handle multiple operations simultaneously without risking data corruption.
+
+4. **Game Applications**: In multiplayer online games, actors can represent various entities such as players, non-player characters (NPCs), items, and game rooms. Each actor encapsulates its state and behavior, interacting through messages to create a dynamic and responsive game world.
+
+### Architectural Decisions Influenced by Actor Model Constraints
+
+Implementing the Actor Model in business applications necessitates careful architectural planning due to its unique constraints and capabilities:
+
+1. **State Management**: Actors maintain their state internally and do not share state. This requires designing the system in such a way that all necessary information is passed through messages. This may involve breaking down complex processes into smaller, message-driven interactions.
+
+2. **Message Passing**: Since actors communicate solely through asynchronous messages, it’s essential to design a robust messaging infrastructure. This includes choosing appropriate messaging protocols, ensuring message delivery guarantees (e.g., at-least-once, at-most-once, or exactly-once delivery), and handling message serialization/deserialization.
+
+3. **Error Handling and Supervision**: Actors can supervise other actors, which means designing a supervision strategy is crucial. This involves defining how actors should respond to failures—whether they should restart, escalate the error, or stop entirely. Effective supervision trees help in building resilient applications.
+
+4. **Distributed Coordination**: In distributed systems, coordinating actors across multiple nodes can be challenging. Architectural decisions should account for network partitions, latency, and data consistency. Utilizing Spawn framework can simplify these aspects by providing built-in support for distributed actor systems.
+
+5. **Scalability Considerations**: Scaling an actor-based system requires monitoring actor workloads and ensuring that actors are efficiently distributed across available resources. Load balancing strategies and dynamic actor creation/destruction policies need to be defined to maintain optimal performance.
+
+### Granularity of Actors and Its Impact
+
+One critical architectural decision in the Actor Model is determining the granularity of actors. Granularity refers to the size and number of actors within the system, affecting both performance and maintainability.
+
+#### Fine-Grained vs. Coarse-Grained Actors
+
+1. **Fine-Grained Actors**: In this approach, actors are small, representing very specific tasks or entities. For example, each item in an inventory system might be an individual actor.
+    - **Pros**: High concurrency, fine control over individual components, easier to scale specific parts of the system.
+    - **Cons**: Higher overhead due to the increased number of actors, potential performance issues due to frequent message passing, complex actor management.
+
+2. **Coarse-Grained Actors**: Here, actors represent larger aggregates, such as an entire inventory or order processing system.
+    - **Pros**: Reduced overhead, fewer messages, simpler management.
+    - **Cons**: Reduced concurrency, potential bottlenecks if a single actor becomes overwhelmed, more complex internal state management.
+
+### Managing Granularity
+
+To effectively manage granularity, consider the following strategies:
+
+1. **Profiling and Performance Testing**: Continuously monitor the performance of your actor system. Identify bottlenecks and adjust the granularity accordingly. Profiling tools specific to actor systems, such as those available in Spawn, can help pinpoint performance issues.
+
+2. **Dynamic Actor Creation**: Use patterns like actor hierarchies and dynamic actor creation to balance the load. For instance, a coarse-grained actor can create fine-grained child actors to handle specific tasks when needed, thus balancing load dynamically.
+
+3. **State Partitioning**: Partition state across multiple actors where applicable. In a fine-grained system, ensure that each actor holds only the necessary state for its specific responsibility, reducing the overhead of managing large states.
+
+4. **Batch Processing**: In some cases, batch processing within actors can reduce the message-passing overhead. Group related tasks and process them in batches within a single actor, which can be particularly useful in coarse-grained systems.
+
+### Modeling Actors as Business Entities
+
+In business applications, actors can be modeled as business entities to better align with real-world processes and operations. Here’s how to effectively model actors as business entities like users, transactions, and more:
+
+1. **User Actors**: Each user can be represented as an actor, encapsulating the user's state, preferences, and actions. This actor can handle messages related to user authentication, profile updates, and interaction with other parts of the system.
+    - **Example**: In a social media platform, a user actor might manage friend requests, message notifications, and content creation.
+
+2. **Transaction Actors**: Transactions in financial systems can be modeled as actors to ensure secure and isolated processing. Each transaction actor handles the entire lifecycle of a transaction, from initiation to completion, including rollback in case of failures.
+    - **Example**: In a banking application, a transaction actor can manage the transfer of funds between accounts, ensuring consistency and integrity.
+
+3. **Order Actors**: For e-commerce platforms, orders can be represented as actors. Each order actor manages the stages of the order lifecycle, such as validation, payment processing, inventory update, and shipping.
+    - **Example**: An order actor can interact with inventory actors to check stock availability and with payment actors to process transactions.
+
+4. **Game Entities**: In a game application, actors can represent various game entities such as players, NPCs, items, and game rooms. Each game entity actor manages its state and behavior, interacting through messages to create a dynamic and interactive game environment.
+    - **Example**: In a multiplayer online game, player actors manage individual player states, NPC actors handle non-player character behavior, and item actors represent in-game objects like weapons and power-ups.
+
+### Actor Model and Architectural Patterns
+
+Actors can be used to implement various architectural patterns, enhancing the robustness and scalability of business applications:
+
+1. **Saga Pattern**: The Saga pattern is used to manage long-running transactions by breaking them into a series of smaller, isolated transactions that can be individually committed or compensated. Actors are well-suited for implementing the Saga pattern due to their message-passing capabilities and independent state management.
+    - **Implementation**: Each step of a saga can be an actor, with a coordinator actor managing the overall process. The coordinator sends messages to initiate each step and handles compensation actions in case of failures.
+
+2. **Event Sourcing**: Actors can be used to implement event sourcing, where changes to the state are stored as a sequence of events. Each actor can manage its event log, ensuring that the state can be reconstructed by replaying events.
+    - **Implementation**: An order actor, for instance, can log events such as "OrderPlaced," "PaymentProcessed," and "OrderShipped." Replaying these events can reconstruct the current state of the order.
+
+3. **CQRS (Command Query Responsibility Segregation)**: In a CQRS architecture, actors can handle commands (state-changing operations) and queries (read operations) separately, improving scalability and performance.
+    - **Implementation**: Command actors handle operations that modify the state, while query actors provide read-only views of the state. This separation can enhance performance by allowing the system to scale read and write operations independently.
+
+4. **State Machines**: Actors can represent state machines, where each state of the actor corresponds to a different behavior. This is particularly useful in scenarios where an entity has a well-defined lifecycle with distinct states.
+    - **Implementation**: Consider a user registration process. The user actor can have states like "New," "Email
+
+Sent," "Verified," and "Active." Each state defines how the actor responds to messages, enabling clear and maintainable transitions.
+
+### Conclusion
+
+The Actor Model offers a robust paradigm for building scalable, resilient, and maintainable software systems. By embracing message-passing and encapsulating state within actors, developers can address the complexities of concurrency and distribution effectively. In business applications, this model can streamline processes such as order handling, customer interactions, financial transactions, and game interactions. The granularity of actors significantly impacts system performance and maintainability, requiring careful management through profiling, dynamic actor creation, state partitioning, and batch processing. Additionally, actors can be modeled as business entities, aligning system design with real-world processes. By implementing architectural patterns like Sagas, Event Sourcing, CQRS, and State Machines, the Actor Model can enhance the robustness and scalability of a wide range of applications.
+
+[Next: Index](index.md)
+
+[Previous: History](history.md)