Nodes and Workers
Ockam Nodes and Workers decouple applications from the host environment and enable simple interfaces for stateful and asynchronous message-based protocols.
At Ockam's core is a collection of cryptographic and messaging protocols. These protocols make it possible to create private and secure by design applications that provide end-to-end application layer trusted data.
Ockam is designed to make these powerful protocols easy and safe to use in any application environment – from highly scalable cloud services to tiny battery operated microcontroller based devices.
However, many of these protocols require multiple steps and have complicated internal state that must be managed with care. It can be quite challenging to make them simple to use, secure, and platform independent.
An Ockam Node is any program that can interact with other Ockam Nodes using various Ockam protocols like Ockam Routing and Ockam Secure Channels.
You can create a standalone node using Ockam Command or embed one directly into your application using various Ockam programming libraries. Nodes are built to leverage the strengths of their operating environment. Our Rust implementation, for example, makes it easy to adapt to various architectures and processors. It can run efficiently on tiny microcontrollers or scale horizontally in cloud environments.
A typical Ockam Node is implemented as an asynchronous execution environment that can run very lightweight, concurrent, stateful actors called Ockam Workers. Using Ockam Routing, a node can deliver messages from one worker to another local worker. Using Ockam Transports, nodes can also route messages to workers on other remote nodes.
Ockam Command makes it super easy to create and manage local or remote nodes. If you run
ockam node create, it will create and start a node in the background and give it a random name:» ockam node create
✔︎ Node f8eb8df9 created successfully
Similarly, you can also create a node with a name of your choice:
» ockam node create n1
✔︎ Node n1 created successfully
You could also start a node in the foreground and optionally tell it display verbose logs:
» ockam node create n2 --foreground --verbose
2023-05-18T09:54:24.281248Z INFO ockam_node::node: Initializing ockam node
2023-05-18T09:54:24.298089Z INFO ockam_command::node::util: node state initialized name=n2
2023-05-18T09:54:24.298906Z INFO ockam_node::processor_builder: Initializing ockam processor '0#c20e2e4aeb9fbae2b5be1529c83af54d' with access control in:DenyAll out:DenyAll
2023-05-18T09:54:24.299627Z INFO ockam_api::cli_state::nodes: setup config updated name=n2
2023-05-18T09:54:24.302206Z INFO ockam_api::nodes::service: NodeManager::create: n2
2023-05-18T09:54:24.302218Z INFO ockam_api::nodes::service: NodeManager::create: starting default services
2023-05-18T09:54:24.302286Z INFO ockam_node::worker_builder: Initializing ockam worker '0#_internal.nodemanager' with access control in:AllowAll out:AllowAll
2023-05-18T09:54:24.302719Z INFO ockam_node::worker_builder: Initializing ockam worker '0#ockam.ping.collector' with access control in:AllowAll out:DenyAll
2023-05-18T09:54:24.302728Z INFO ockam_node::worker_builder: Initializing ockam worker '0#identity_service' with access control in:AllowAll out:AllowAll
2023-05-18T09:54:24.303179Z INFO ockam_node::worker_builder: Initializing ockam worker '0#authenticated' with access control in:AllowAll out:AllowAll
2023-05-18T09:54:24.303364Z INFO ockam_node::worker_builder: Initializing ockam worker '0#uppercase' with access control in:AllowAll out:AllowAll
2023-05-18T09:54:24.303527Z INFO ockam_node::worker_builder: Initializing ockam worker '0#forwarding_service' with access control in:AllowAll out:DenyAll
2023-05-18T09:54:24.303851Z INFO ockam_node::worker_builder: Initializing ockam worker '0#api' with access control in:AllowAll out:DenyAll
2023-05-18T09:54:24.304009Z INFO ockam_node::worker_builder: Initializing ockam worker '0#echo' with access control in:AllowAll out:AllowAll
2023-05-18T09:54:24.304056Z INFO ockam_node::worker_builder: Initializing ockam worker '0#rpc_proxy_service' with access control in:AllowAll out:AllowAll
...
To stop the foreground node, you can press
Ctrl-C. This will stop the node but won't delete its state.You can see all running nodes with
ockam node list» ockam node list
┌───────────────────┐
│ Nodes │
└───────────────────┘
│ Node n1 UP
│ Process id 42218
│ Node f8eb8df9 (default) UP
│ Process id 42083
│ Node n2 DOWN
│ No process running
...
You can stop a running node with
ockam node stop.» ockam node stop n1
You can start a stopped node with
ockam node start.» ockam node start n1
You can permanently delete a node by running:
» ockam node delete n1
✔︎ The node named 'n1' has been deleted.
You can also delete all nodes with:
» ockam node delete --all
Ockam Nodes run very lightweight, concurrent, and stateful actors called Ockam Workers. They are like processes on your operating system, except that they all live inside one node and are very lightweight so a node can have hundreds of thousands of them, depending on the capabilities of the machine hosting the node.
When a worker is started on a node, it is given one or more addresses. The node maintains a mailbox for each address and whenever a message arrives for a specific address it delivers that message to the corresponding worker. In response to a message, a worker can: make local decisions, change internal state, create more workers, or send more messages.
You can see the list of workers in a node by running:
» ockam node create n1
» ockam worker list --at n1
┌───────────────────────────┐
│ Workers on n1 │
└───────────────────────────┘
│ Worker 0c240525017e2273fa58fc0d5497b62a
│ Worker 31482d2647246b47667cf12428626723
│ Worker 4248c83401c77176967715caca9d82dd
│ Worker _internal.nodemanager
...
Note the workers in node
n1 with address echo and uppercase. We'll send them some messages below as we look at services. A node can also deliver messages to workers on a different node using the Ockam Routing Protocol and its Transports. Later in this guide, when we dig into routing, we'll send some messages across nodes.Workers are stateful and can asynchronously send and receive messages. This makes them a potent abstraction that can take over the responsibility of running multistep, stateful, and asynchronous message-based protocols. This enables
ockam command and Ockam Programming Libraries to expose very simple and safe interfaces for powerful protocols.One or more Ockam Workers can work as a team to offer a Service. Services can also be attached to a trust context and authorization policies to enforce attribute based access control rules.
For example, nodes that are created with Ockam Command come with some predefined services including an example service
/service/uppercase that responds with an uppercased version of whatever message you send it:» ockam message send hello --to /node/n1/service/uppercase
HELLO
Services have addresses represented by
/service/{ADDRESS}. You can see a list of all services on a node by running:» ockam service list --at n1
┌────────────────────────────┐
│ Services on n1 │
└────────────────────────────┘
│ Service uppercase
│ Address /service/uppercase
│ Service echo
│ Address /service/echo
│ Service credentials
│ Address /service/credentials
Later in this guide, we'll explore other commands that interact with pre-defined services. For example every node created with
ockam command starts a secure channel listener at the address /service/api, which allows other nodes to create mutually authenticated secure channels with it.Ockam Spaces are infinitely scalable Ockam Nodes in the cloud. Ockam Orchestrator can create, manage, and scale spaces for you. Like other nodes, Spaces offer services. For example, you can create projects within a space, invite teammates to it, or attach payment subscriptions.
When you run
ockam enroll for the first time, we create a space for you to host your projects.» ockam enroll
...
» ockam space list
┌────────────────────┐
│ Spaces │
└────────────────────┘
│ Space f27d39e1
│ Id 877c7a4d-b1be-4f36-8da6-be045ab64b60
When you run
ockam enroll for the first time, we create a default project for you, within your default space.» ockam enroll
...
» ockam project list
┌──────────────────────┐
│ Projects │
└──────────────────────┘
│ Project default
│ Space f27d39e1
Like other nodes, Projects offer services. For example, the default project has an
echo service just like the local nodes we created above. We can send messages and get replies from it. The echo service replies with the same message we send it.» ockam message send hello --to /project/default/service/echo
hello
To clean up and delete all nodes, run:
ockam node delete --allOckam Nodes are programs that interact with other nodes using one or more Ockam protocols like Routing and Secure Channels. Nodes run very lightweight, concurrent, and stateful actors called Workers. Nodes and Workers hide complexities of environment and state to enable simple interfaces for stateful, asynchronous, message-based protocols.
One or more Workers can work as a team to offer a Service. Services can be attached to trust contexts and authorization policies to enforce attribute based access control rules. Ockam Orchestrator can create and manage infinitely scalable nodes in the cloud called Spaces and Projects that offer managed services that are designed for scale and reliability.
Next, let's learn about Ockam's Application Layer Routing and how it enables protocols that provide end-to-end guarantees to messages traveling across many network connection hops and protocols boundaries.
Last modified 1mo ago