TEP-1: Unchained Plugins Alpha How-To

We're excited to announce the alpha release of TEP-1: Unchained Plugins! This release is a major milestone for Timeleap, as it marks the first step towards a more flexible and extensible Unchained platform. You can now make your own plugins and add custom functionality to Unchained. This article will guide you through the process of creating your first Unchained plugin.

How does a plugin work?

A plugin is a piece of code that connects to an Unchained broker and registers a set of functions that can be called by other users. Brokers are responsible for accepting and routing messages between users and plugins. When a user sends a message to a plugin, the broker forwards the message to the plugin, which processes it and sends a response back to the user.

Since the official Unchained Plugin SDK is still in development, we'll be using the low-level Unchained API to create our plugin. We'll also develop a simple client that can interact with our plugin through the broker.

Setting up your development environment

We're going to use TypeScript to write our plugin and client. We'll also use Yarn to manage our dependencies. If you don't have Yarn installed, you can follow the instructions on their official website to install it. Once you have Yarn installed, you can create a new project by running:

Let's initialize a new TypeScript project by running:

You should also initate Yarn dlx. Assuming you use VSCode, you can run the following command:

You need to make two more changes to your project. First, create a tsconfig.json file in the root of your project with the following content:

Next, modify your package.json file to include the following:

You can follow the exact same steps for the unchained-client project. Once you're done, you can start writing your plugin and client.

Writing your plugin

Let's start by adding the required dependencies to our project:

Next, create a new file called src/index.ts. I'll walk you through the process of creating a very simple plugin with one function that returns a greeting message and whether the user is a wizard or not!

We start by the imports:

Next, we create a new WebSocket server on port 3000:

Now we need to listen to incoming connections and messages. When a user sends a message to the broker, it gets forwarded to the plugin. We can then process the message and send a response back to the user:

Now, let's add the logic to our plugin. We'll create a new Sia instance to read and write messages to the broker. This code goes inside the message event handler:

Finally, let's add a simple log message to indicate that the WebSocket server has started:

That's it! You've just created your first Unchained plugin. You can see the full source code of the plugin in the TEP Examples GitHub repository. To build and run the plugin, you can run the following commands:

Writing your client

Now that we have our plugin up and running, let's create a simple client that can interact with it. We'll use the WebSocket client from the ws package to connect to the broker and send messages to the plugin. Create a new project named unchained-client by following the steps in the Setting up your development environment section.

Next, add the required dependencies to your project:

Next, create a new file called src/index.ts. We'll walk you through the process of creating a simple client that sends a message to the plugin and prints the response.

We start by the imports:

Let's add some initializations:

Let's create a payload now to send to the plugin:

Add some logs so we know what's happening:

Now, let's send the payload to the plugin:

Finally, let's listen for the response from the plugin:

That's it! You've just created your first Unchained client. You can see the full source code of the client in the TEP Examples GitHub repository. To build the client you can run the following command:

But don't run the client just yet! First, we need to register the plugin with the broker. We'll cover that in the next section.

Configuring Unchained

Let's configure and run a local Unchained broker and worker to test our plugin and client. Make sure you have the latest version of the Unchained CLI installed. You can find the latest version on the Unchained GitHub releases page.

First, create a new directory for your Unchained project:

Now we need to create a new Unchained configuration file. We'll create one file for both the broker and the worker. Create a new file called conf.yaml with the following content:

That's it! You're now ready to start the entire project.

Running the project

To run the project, you need to start the broker and worker. You can do this by running the following commands:

You should see the broker and worker start up successfully. You should also see a message indicating that the plugin has been registered with the broker.

Now you can run the client to interact with the plugin. You should see a message indicating whether the user is a wizard or not. You can run the client by this command in the unchained-client directory:

You should see the client connect to the broker, send a message to the plugin, and receive a response back. If everything is working correctly, you should see a message indicating whether the user is a wizard or not:

Congratulations! You've successfully created your first Unchained plugin and client. You can now start experimenting with different plugins and clients to build your own Unchained applications. As of now, Sia is available in TypeScript, Python, and Go.

If you have any questions or need help, feel free to post an issue on the Unchained GitHub repository or the Timeleap Forum.