Getting Started

To begin, you'll need to develop your HostFunction application. Refer to the documentation for each SDK to learn how to proceed with your preferred programming language.

Using Elixir SDK
Using Java SDK
Using NodeJS SDK
Using Python SDK

Alternatively, you can quickly scaffold a Spawn application using the CLI.

For example, to create a NodeJS application template, run the following command:

spawn new node hello_world

This will generate output similar to the following:

Next, navigate to your newly created application's directory, install dependencies, and start the application:

cd hello_world; yarn && yarn start

The output should look something like this:

Spawn uses a lightweight proxy that handles the underlying implementation of services and provides infrastructure for your application. To fully test your services, you'll need to run this proxy in your development environment.

Run the following command to start the proxy:

spawn dev run -p ./protos -s spawn-system -W

Once the proxy is up and running, you can invoke your application's actors. In this NodeJS example, Spawn uses gRPC-HTTP transcoding to convert HTTP requests into actor invocations. You can call your actor by sending an HTTP request like this:

curl -vvv -H 'Accept: application/json' http://localhost:9980/v1/hello_world?message=World

NOTE: Ensure you're sending requests to the gRPC port displayed in the console when the proxy is running. The proxy transparently handles the conversion between HTTP and actor invocations. For more details on how the transcoding engine works, refer to each SDK's documentation.

You can also check out the following gif for another example:

Once you have done the initial setup you can start developing your actors in several available languages. See below how easy it is to do this in some languages:

NodeJS

import spawn, { ActorContext, Value } from '@eigr/spawn-sdk'
import { UserState, ChangeUserNamePayload, ChangeUserNameStatus } from 'src/protos/examples/user_example'

const system = spawn.createSystem('SpawnSystemName')

const actor = system.buildActor({
  name: 'joe',
  stateType: UserState, // or 'json' if you don't want to use protobufs
  stateful: true,
})

const setNameHandler = async (context: ActorContext<UserState>, payload: ChangeUserNamePayload) => {
  return Value.of<UserState, ChangeUserNameResponse>()
    .state({ name: payload.newName })
    .response(ChangeUserNameResponse, { status: ChangeUserNameStatus.OK })
}

actor.addAction({ name: 'setName', payloadType: ChangeUserNamePayload }, setNameHandler)

Elixir

defmodule SpawnSdkExample.Actors.MyActor do
  use SpawnSdk.Actor,
    name: "joe",
    kind: :named,
    stateful: true, 
    state_type: Io.Eigr.Spawn.Example.MyState, # or :json if you don't care about protobuf types
  
  require Logger
  
  alias Io.Eigr.Spawn.Example.{MyState, MyBusinessMessage}

  action "Sum", fn %Context{state: state} = ctx, %MyBusinessMessage{value: value} = data ->
    Logger.info("Received Request: #{inspect(data)}. Context: #{inspect(ctx)}")
    new_value = if is_nil(state), do: value, else: (state.value || 0) + value

    Value.of(%MyBusinessMessage{value: new_value}, %MyState{value: new_value})
  end
end

Java

package io.eigr.spawn.java.demo;

import io.eigr.spawn.api.actors.ActorContext;
import io.eigr.spawn.api.actors.StatefulActor;
import io.eigr.spawn.api.actors.Value;
import io.eigr.spawn.api.actors.behaviors.ActorBehavior;
import io.eigr.spawn.api.actors.behaviors.BehaviorCtx;
import io.eigr.spawn.api.actors.behaviors.NamedActorBehavior;
import io.eigr.spawn.api.actors.ActionBindings;
import domain.Reply;
import domain.Request;
import domain.State;

import static io.eigr.spawn.api.actors.behaviors.ActorBehavior.*;

public final class JoeActor implements StatefulActor<State> {
  @Override
  public ActorBehavior configure(BehaviorCtx context) {
      return new NamedActorBehavior(
              name("JoeActor"),
              channel("test.channel"),
              action("SetLanguage", ActionBindings.of(Request.class, this::setLanguage))
      );
  }

  private Value setLanguage(ActorContext<State> context, Request msg) {
      if (context.getState().isPresent()) {
          //Do something with previous state
      }

      return Value.at()
              .response(Reply.newBuilder()
                      .setResponse(String.format("Hi %s. Hello From Java", msg.getLanguage()))
                      .build())
              .state(updateState(msg.getLanguage()))
              .reply();
  }

  private State updateState(String language) {
      return State.newBuilder()
              .addLanguages(language)
              .build();
  }
}

Python

from domain.domain_pb2 import JoeState, Request
from spawn.eigr.functions.actors.api.actor import Actor
from spawn.eigr.functions.actors.api.settings import ActorSettings
from spawn.eigr.functions.actors.api.context import Context
from spawn.eigr.functions.actors.api.value import Value

actor = Actor(settings=ActorSettings(
    name="joe", stateful=True, channel="test"))

@actor.action("setLanguage")
def set_language(request: Request, ctx: Context) -> Value:
    new_state = None

    if not ctx.state:
        new_state = JoeState()
        new_state.languages.append("python")
    else:
        new_state = ctx.state

    return Value().state(new_state).noreply()

Rust

use spawn_examples::domain::domain::{Reply, Request, State};
use spawn_rs::{value::Value, Context, Message};

use log::info;

pub fn set_language(msg: Message, ctx: Context) -> Value {
    info!("Actor msg: {:?}", msg);
    return match msg.body::<Request>() {
        Ok(request) => {
            let lang = request.language;
            info!("Setlanguage To: {:?}", lang);
            let mut reply = Reply::default();
            reply.response = lang;

            match &ctx.state::<State>() {
                Some(state) => Value::new()
                    .state::<State>(&state.as_ref().unwrap(), "domain.State".to_string())
                    .response(&reply, "domain.Reply".to_string())
                    .to_owned(),
                _ => Value::new()
                    .state::<State>(&State::default(), "domain.State".to_string())
                    .response(&reply, "domain.Reply".to_string())
                    .to_owned(),
            }
        }
        Err(_e) => Value::new()
            .state::<State>(&State::default(), "domain.State".to_string())
            .to_owned(),
    };
}

Deploy

Once your container is built and contains the Actor Host Function (following the SDK recommendations above), it's time to deploy it to a Kubernetes cluster with the Spawn Operator installed. See the installation section for more details on this process.

In this tutorial, we will use a MariaDB database. To allow Spawn to connect to your database instance, you'll first need to create a Kubernetes secret in the same namespace where you installed the Spawn Operator. This secret will store the connection details and other required parameters. Here's an example:

kubectl create secret generic mariadb-connection-secret -n eigr-functions \
  --from-literal=database=eigr-functions-db \
  --from-literal=host='mariadb' \
  --from-literal=port='3306' \
  --from-literal=username='admin' \
  --from-literal=password='admin' \
  --from-literal=encryptionKey=$(openssl rand -base64 32)

Spawn securely encrypts the Actor's state, so the encryptionKey must be provided. Ensure the key is of sufficient length and complexity to protect your data.

NOTE: For more information on Statestore settings, see the statestore section.

If your project uses the Activators or Projection feature or if you need your Actors to communicate between different ActorSystems, you'll also need to create a secret with connection details for the Nats server. Here's how:

NOTICE: This tutorial does not cover installing Nats, but you can install it in Kubernetes with these commands: helm repo add nats https://nats-io.github.io/k8s/helm/charts/ && helm install spawn-nats nats/nats.

Now, create a configuration file with Nats credentials:

kubectl -n default create secret generic nats-invocation-conn-secret \
  --from-literal=url="nats://spawn-nats:4222" \
  --from-literal=authEnabled="false" \
  --from-literal=tlsEnabled="false" \
  --from-literal=username="" \
  --from-literal=password=""

Next, in your preferred directory, create a file called system.yaml with the following content:

---
apiVersion: spawn-eigr.io/v1
kind: ActorSystem
metadata:
  name: spawn-system # 1. Required. Name of the ActorSystem
  namespace: default # 2. Optional. Default namespace is "default"
spec:
  # This externalInvocation section is required only if using the Nats broker in your project.
  externalInvocation:
    enabled: "true"
    externalConnectorRef: nats-invocation-conn-secret # 3. Nats broker credentials
  statestore:
    type: MariaDB # 4. Set database provider. Valid options: [MariaDB, Postgres, Native]
    credentialsSecretRef: mariadb-connection-secret # 5. Secret with database connection details created earlier
    pool: # Optional
      size: "10"

This file defines your ActorSystem within the Kubernetes cluster.

Now, create another file called host.yaml with the following content:

---
apiVersion: spawn-eigr.io/v1
kind: ActorHost
metadata:
  name: spawn-springboot-example # 1. Required: Name of the node hosting Actor Functions
  namespace: default # 2. Optional: Default namespace is "default"
  annotations:
    # 3. Required: ActorSystem name as declared in ActorSystem CRD
    spawn-eigr.io/actor-system: spawn-system
spec:
  host:
    image: eigr/spawn-springboot-examples:latest # 4. Required: Container image
    ports:
      - name: "http"
        containerPort: 8091

This file handles the deployment of your host function and actors.

If you’re using the Elixir SDK, your YAML file should look like this:

---
apiVersion: spawn-eigr.io/v1
kind: ActorHost
metadata:
  name: spawn-dice-game
  namespace: default
  annotations:
    spawn-eigr.io/actor-system: game-system
spec:
  host:
    embedded: true # Indicates a native BEAM application, so no sidecar proxy is needed
    image: eigr/dice-game-example:1.4.3
    ports:
      - name: "http"
        containerPort: 8800

Once the files are defined, apply them to the cluster with the following commands:

kubectl apply -f system.yaml
kubectl apply -f host.yaml

Finally, check your deployed actors with:

kubectl get actorhosts

Examples

Here are some project examples using Spawn:

Hatch: https://github.com/zblanco/hatch
Elixir Dice Game. (Spawn with Phoenix app): https://github.com/eigr-labs/spawn_game_example.git
Distributed Image Processing: https://github.com/eigr-labs/spawn-distributed-image-processing
Federated Data Example: https://github.com/eigr-labs/spawn-federated-data-example
Fleet: https://github.com/sleipnir/fleet-spawn-example
Postal Code Search: https://github.com/h3nrique/postalcode-spawn-demo
Spawn Polyglot Example: https://github.com/sleipnir/spawn-polyglot-ping-pong

In the next section, you'll find links to each supported SDK.

NOTICE: Not all examples may be up to date with the latest versions of Spawn and its SDKs.

Back to Index

Next: SDKs

Previous: Install

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

getting_started.md

getting_started.md

Getting Started

Deploy

Examples

Files

getting_started.md

Latest commit

History

getting_started.md

File metadata and controls

Getting Started

Deploy

Examples