Now that we have a Savi compiler installed, it’s time to put it through the paces of building a simple application.

Let’s build an echo server - a TCP listener that simply echoes whatever bytes it receives from its clients back to them.

We’ll start by creating a simple git repository. This is not strictly necessary for using Savi, but it’s a good development practice to have somewhere to commit your work incrementally.

Now let’s use Savi to initialize a small bit of boilerplate code for a new executable binary, to be named echo-server.

Let’s take a look at manifest.savi, which was created to declare the echo-server executable binary and specify where to find the source files for it.

And we can look at src/Main.savi, which was created to declare what the Main actor of the program should do.

The Main actor is the entry point of the program. When created, it is given an object of type Env as its constructor argument, giving it the capability to take actions that have side effects.

So far, we only use the Env object to print "Hello, World!".

Now let’s build it, using the Savi compiler.

There’s only one manifest so far, so we don’t need to specify echo-server explicitly.

Savi created an executable binary called bin/echo-server, which we can now run.

Great, so now we know that we can build and run a basic program, but it’s not a TCP server yet.

If we look at the Savi library index, we see that in the “Standard Library” section there is a library named TCP that probably can do what we want.

So let’s add TCP as a dependency.

We also want to add a simple logger that we can easily pass around our application.

So let’s add Logger as a dependency as well.

If we look again at our manifest.savi file we can see it has been automatically modified by Savi to show the TCP dependency, as well as the transitive dependencies that it depends on (ByteStream, IO, OSError, and IPAddress). Then we see the Logger dependency and its transitive dependency (Time).

In the manifest, Savi shows us where each of these libraries is sourced from and how they depend on one another. When this file is committed to a shared repository along with other source code changes, code reviewers will be able to see the dependency structure and how it changes over time.

Like all other declarative constructs in Savi, each declaration line begins with a :-prefixed keyword that lets the parser know to treat the line as a declaration.

The order of declarations doesn’t matter, and Savi won’t reorder existing declarations in the manifest when changing dependencies, so you can feel free to reorder the declarations in whatever order you think is easiest to audit. You can also add comments - those will be preserved as well. Or just leave it alone and let the Savi compiler manage this file by itself.

We notice that the Logger library suggests creating a type alias with the preferred formatter module declared for our project. So let’s do that first.

Create a new file named src/_Log.savi and put the :alias declaration there.

In truth, it doesn’t matter what you name the file (we never need to refer to specific files by name in Savi) as long as it matches the src/*.savi pattern that was set up in the manifest. But by convention we name the file with the name of the type declared within it, adding the .savi filename suffix, making it easy to find things.

Now let’s implement our echo server!

In a file named src/EchoServer.savi, we declare an actor named EchoServer that uses the IO.Actor trait and a TCP.Engine field to act as a TCP connection actor. It also holds a _Log instance so it can log messages.

The constructor takes two arguments: a _Log instance (written directly into the log field), as well a “ticket” that represents a pending TCP connection waiting to be accepted (which is used to set up the io field). It’s always required to initialize all fields before the constructor is finished.

The actor reacts to IO.Action.Read by reading all available bytes from the @io.read_stream and sending them to the @io.write_stream (as well as logging them, if the logger is configured to show debug logs). This is the echo behavior of our echo server.

If we try to compile this program now with savi build we see an error telling us it couldn’t find the IO.Actor type, which may seem strange, because we saw earlier that the IO library is already in our manifest.

However, we note that it’s currently there as a transitive dependency. Only direct dependencies will be in scope for type resolution, so if we want to use the IO type we need to load it in as a direct dependency.

After this, our code should compile successfully again.

Now that we have an actor that can handle echoing on a TCP connection, we need a TCP listener actor that can listen for new TCP connections.

Let’s create src/EchoServer.Listener.savi with a new EchoServer.Listener actor.

It is also an IO.Actor, and it takes a logger and a ticket, but it uses TCP.Listen.Engine instead of TCP.Engine for its io field, which means that it deals with IO actions differently.

When it’s begun listening (on IO.Action.Opened), our actor will log its port number. For every new pending connection (on IO.Action.Read), it creates a new EchoServer actor to accept and manage the connection, by passing the ticket for the connection to that actor.

That’s pretty much it!

The last step is to hook into the main entrypoint of the program in src/Main.savi so that it creates the listener (instead of just printing “Hello, World!” as it does now).

Our Main actor is responsible for kicking off the program and delegating the right amount of authority to the actors in it. By holding the Env it has the authority to do anything, but it can (and should) attenuate that authority according to the principle of least privilege.

In this case, we use the env to create a _Log instance that can log to standard error output (env.err), and we create a TCP listen ticket that can listen on a particular host and port.

In this example, the host is hard-coded and the port is taken from the first CLI argument (if present). The CLI user may specify a number (such as 80) or a name (such as http) or leave the argument so that the program uses the default empty string, which allows the listener to choose any arbitrary open port.

Now we can build and run again, specifying a particular listen port if we wish.

We’ll see it log when it’s started listening.

We can connect to our echo server with the telnet command in a separate terminal.

Once connected, if we type something in the telnet terminal we’ll see it echoed back to us, and we’ll also see it logged in the server as debug-level log messages.

That’s it for this tutorial!

If you enjoyed this, please consider committing the source code as a public repository on GitHub. It will help us get GitHub to recognize our language and enable syntax highlighting (they require a threshold number of repositories before they will allow our language to be detected).