Spawn Go SDK

Seamless Actor Mesh Runtime for Go Developers

---

🚀 Why Choose Spawn?

• Developer Friendly: Simplify building distributed, stateful applications.
• Scalable: Designed for cloud-native environments with polyglot support.
• Effortless Integration: Build robust systems with minimal boilerplate.

---

🌟 Features

• Fully managed actor lifecycle.
• State persistence and snapshots.
• Polyglot SDKs for ultimate flexibility. In this case GO SDK \0/.
• Optimized for high performance and low latency.

---

📦 Installation

Set up your environment in seconds. Install the Spawn CLI:

curl -sSL https://github.com/eigr/spawn/releases/download/v1.4.3/install.sh | sh

🔥 Getting Started

1️⃣ Create a New Project

spawn new go hello_world

2️⃣ Define Your Protocol

Leverage the power of Protobuf to define your actor's schema:

syntax = "proto3";

package examples.actors;

option go_package = "examples/actors";

message UserState {
  string name = 1;
}

message ChangeUserNamePayload {
  string new_name = 1;
}

message ChangeUserNameResponse {
  // this is a bad example, but it's just an example
  enum ResponseStatus {
    OK = 0;
    ERROR = 1;
  }
  ResponseStatus response_status = 1;
}

service UserActor {
  rpc ChangeUserName(ChangeUserNamePayload) returns (ChangeUserNameResponse) {}
}

3️⃣ Compile Your Protobuf

Follow the example in our Makefile.

4️⃣ Implement Your Business Logic

Start writing actors with ease:

package main

import (
	"fmt"
	"log"
	"time"

	domain "examples/actors"

	spawn "github.com/eigr/spawn-go-sdk/spawn/actors"
	actorSystem "github.com/eigr/spawn-go-sdk/spawn/system"
	"google.golang.org/protobuf/proto"
)

func main() {
	// Defines the actor configuration
	actorConfig := spawn.ActorConfig{
		Name:               "UserActor",         // Name of ator
		StateType:          &domain.UserState{}, // State type
		Kind:               spawn.Named,         // Actor Type (Named)
		Stateful:           true,                // Stateful actor
		SnapshotTimeout:    60,                  // Snapshot timeout
		DeactivatedTimeout: 120,                 // Deactivation timeout
	}

	// Creates an actor directly
	userActor := spawn.ActorOf(actorConfig)

	// Define a simple action for the actor
	userActor.AddAction("ChangeUserName", func(ctx *spawn.ActorContext, payload proto.Message) (spawn.Value, error) {
		// Convert payload to expected type
		log.Printf("Received invoke on Action ChangeUserName. Payload: %v", payload)
		input, ok := payload.(*domain.ChangeUserNamePayload)
		if !ok {
			return spawn.Value{}, fmt.Errorf("invalid payload type")
		}

		// Updates the status and prepares the response
		newState := &domain.UserState{Name: input.NewName}
		response := &domain.ChangeUserNameResponse{ResponseStatus: domain.ChangeUserNameResponse_OK}

		// Returns response to caller and persist new state
		return spawn.Of(response).
			State(newState).
			Materialize(), nil
	})

	// Initializes the Spawn system
	system := actorSystem.NewSystem("spawn-system").
		UseProxyPort(9001).
		ExposePort(8090).
		RegisterActor(userActor)

	// Start the system
	if err := system.Start(); err != nil {
		log.Fatalf("Failed to start Actor System: %v", err)
	}

	resp, _ := system.Invoke(
		"spawn-system",
		"UserActor",
		"ChangeUserName",
		&domain.ChangeUserNamePayload{NewName: "Joe"},
		actorSystem.Options{})

	log.Printf("Response: %v", resp)

	system.Await()
}

5️⃣ Build and generate application in dev mode

go build -v -gcflags="all=-N -l" -o ./bin/examples/app ./examples

6️⃣ Start Spawn CLI in dev mode

spawn dev run

Expected output similar to this:

🏃  Starting Spawn Proxy in dev mode...
❕  Spawn Proxy uses the following mapped ports: [
      Proxy HTTP: nil:9001,
      Proxy gRPC: nil:9980
    ]
🚀  Spawn Proxy started successfully in dev mode. Container Id: 7961ed391e06b36c6d73290a6d6a0cbb60cf910fd4e4ff3fc5b7bd49ed677976

7️⃣ Start application in dev mode

./bin/examples/app

Outputs need to be similar with this:

2024/12/10 20:09:37 HTTP server started on port 8090
2024/12/10 20:09:37 Actors successfully registered and system started

8️⃣ Validate Spawn CLI docker logs

Use Id for previous spawn dev run command to see docker logs.

docker logs -f 7961ed391e06b36c6d73290a6d6a0cbb60cf910fd4e4ff3fc5b7bd49ed677976

Expected output similar to (ommited some logs for brevity):

2024-12-10 21:21:32.028 [proxy@GF-595]:[pid=<0.2770.0> ]:[info]:[Proxy.Config] Loading configs
2024-12-10 21:21:32.029 [proxy@GF-595]:[pid=<0.2770.0> ]:[info]:Loading config: [actor_system_name]:[my-system]
2024-12-10 21:21:32.044 [proxy@GF-595]:[pid=<0.2775.0> ]:[info]:[SUPERVISOR] Sidecar.Supervisor is up
2024-12-10 21:21:32.044 [proxy@GF-595]:[pid=<0.2777.0> ]:[info]:[SUPERVISOR] Sidecar.ProcessSupervisor is up
2024-12-10 21:21:32.045 [proxy@GF-595]:[pid=<0.2779.0> ]:[info]:[SUPERVISOR] Sidecar.MetricsSupervisor is up
2024-12-10 21:21:32.046 [proxy@GF-595]:[pid=<0.2783.0> ]:[info]:[SUPERVISOR] Spawn.Supervisor is up
2024-12-10 21:21:32.048 [proxy@GF-595]:[pid=<0.2791.0> ]:[info]:[SUPERVISOR] Spawn.Cluster.StateHandoff.ManagerSupervisor is up
2024-12-10 21:21:32.053 [proxy@GF-595]:[pid=<0.2809.0> ]:[info]:[mnesiac:proxy@GF-595] mnesiac starting, with []
2024-12-10 21:21:32.078 [proxy@GF-595]:[pid=<0.2809.0> ]:[info]:Elixir.Statestores.Adapters.Native.SnapshotStore Initialized with result {:aborted, {:already_exists, Statestores.Adapters.Native.SnapshotStore}}
2024-12-10 21:21:32.079 [proxy@GF-595]:[pid=<0.2809.0> ]:[info]:[mnesiac:proxy@GF-595] mnesiac started
2024-12-10 21:21:32.083 [proxy@GF-595]:[pid=<0.2855.0> ]:[info]:[SUPERVISOR] Actors.Supervisors.ActorSupervisor is up
2024-12-10 21:21:32.123 [proxy@GF-595]:[pid=<0.2772.0> ]:[info]:Running Proxy.Router with Bandit 1.5.2 at 0.0.0.0:9001 (http)
2024-12-10 21:21:32.124 [proxy@GF-595]:[pid=<0.2770.0> ]:[info]:Proxy Application started successfully in 0.095587ms. Running with 8 schedulers.
2024-12-10 21:21:56.518 [proxy@GF-595]:[pid=<0.3419.0> ]:[info]:POST /api/v1/system
2024-12-10 21:21:56.523 [proxy@GF-595]:[pid=<0.3419.0> ]:[info]:Sent 200 in 4ms
2024-12-10 21:21:56.526 [proxy@GF-595]:[pid=<0.3433.0> ]:[notice]:Activating Actor "UserActor" with Parent "" in Node :"proxy@GF-595". Persistence true.
2024-12-10 21:21:56.528 [proxy@GF-595]:[pid=<0.3424.0> ]:[info]:Actor UserActor Activated on Node :"proxy@GF-595" in 3402ms

📚 Explore More

Check out our examples folder for additional use cases and inspiration.

💡 Why Spawn Matters

CTOs, Tech Leads, and Developers love Spawn for its simplicity, scalability, and flexibility. Build reliable, distributed systems faster than ever.

Unleash the power of polyglot distributed systems with Spawn today!