The Ultimate Guide to Building a Terminal App with Rust and Go
Introduction
TUIs have been around for a pretty long time. They have a lot of use cases, especially in systems like remote servers or embedded systems where there is no GUI. This can be a game changer when you want to have a simple interface to interact with your application without having to install a GUI.
So in this tutorial, we are going to recreate the popular Tic Tac Toe game but with a TUI and with an adjustable grid size and we’ll use chess notation like “A1” and “D4” to identify cells.
The star frameworks of this article are Ratatui the super Rust library for building rich TUI apps and Fiber, the awesome Go web framework for building APIs and lots more.
This article will be divided into 3 sections:
- Setting up the Project
- Go-ing through the Game Server with Fiber V2
- Rust-ling up the TUI with Ratatui
Here is a preview of the wonderful Terminal UI we will be building and this is the Link to the Github Repo if you want to clone it instead as this article is lengthy.
Without wasting any more time, Let’s get started.
Setting up the project
This is an intermediate-level tutorial so you should have at least good programming experience but I will try to explain as much as I can. You also need to have installed Go and Rust on your machine.
If you ever get stuck, be sure to check out the project’s Github Repo for the extensively documented code. This will be a long tutorial so grab your cup of coffee and let’s get started!
Project Structure
You can simply copy and paste this entire code block below into your terminal to create the project structure and files we’ll need for this tutorial:
mkdir tic-tac-to && cd tic-tac-to; \
cargo init --bin client && mkdir client/src/tui; \
cd client/src/tui && touch entry.rs game.rs input.rs mod.rs ui.rs && \
cd - && mkdir server && cd server && go mod init server && mkdir pkg cmd; \
touch cmd/main.go pkg/bot.go pkg/logic.go;Provided you have Rust and Go installed on your machine, the code above will create a new folder called tic-tac-to and initialize a Rust project in the client folder and a Go module in the server folder. It will also create the files we’ll need for this tutorial. Your project structure should look like this:
Dependencies
Now that we have our project structure set up, let’s quickly install the dependencies we’ll need for this project. For the Go side of things, all we need to do is install the Fiber framework, a web framework for Go built on top of FastHttp. It is fast, simple and easy to use. You can check out the documentation to learn more about Fiber.
Run this command in the server directory to install Fiber:
go get -u github.com/gofiber/fiber/v2Now for Rust’s dependencies, in your client directory, update your Cargo.toml file’s dependencies section to look like this:
[dependencies]
crossterm = "0.26"
ratatui = "0.20"
clearscreen = "2.0.1"
figlet-rs = "0.1.5"
tui-input = "0.7.1"
reqwest = { version = "0.11", features = ["blocking", "json"] }
serde_json = "1.0"
serde = { version = "1.0", features = ["derive"] }Here is a quick rundown of the dependencies we’ll be using:
- Ratatui: A library for building terminal user interfaces.
- Crossterm: A cross-platform library for terminal manipulation.
- Clearscreen: A library for clearing the terminal screen.
- Figlet-rs: A library for creating ASCII art from text.
- Tui-input: A library for reading user input from the terminal.
- Reqwest: A library for making HTTP requests.
- Serde_json: A library for serializing and deserializing JSON.
- Serde: A framework for serializing and deserializing Rust data structures efficiently and generically.
Now let’s get into the fun part of this tutorial. Let’s get Going!
Building the Game Server
We’re not building anything too complicated, we just want the server to be able to look at the board and determine if there is a winner or not. If there isn’t a winner or it’s not game over yet, the server should be able to determine the next move simply out of randomness.
Game Logic
So let’s start by implementing the game logic. We’ll create two functions, one to check if there is a winner and another to determine the next move. Copy and paste the code below into the pkg/logic.go file for the checkWin function:
package pkg
import (
"crypto/rand"
"math/big"
)
func checkWin(board [][]int) bool {
n := len(board)
// Check Rows
for _, row := range board {
if row[0] == 0 {
continue
}
won := true
for _, cell := range row {
if row[0] != cell {
won = false
break
}
}
if won {
return true
}
}
// Check Columns
for i := 0; i < n; i++ {
if board[0][i] == 0 {
continue
}
won := true
for j := 0; j < n; j++ {
if board[0][i] != board[j][i] {
won = false
break
}
}
if won {
return true
}
}
// Check Diagonals
if board[0][0] == 0 && board[0][n-1] == 0 {
return false
}
right_won := true
left_won := true
for i := 0; i < n; i++ {
if board[0][0] != board[i][i] && board[0][0] != 0 {
right_won = false
}
if board[0][n-1] != board[i][n-1-i] && board[0][n-1] != 0 {
left_won = false
}
}
if right_won && board[0][0] != 0 || left_won && board[0][n-1] != 0 {
return true
} else {
return false
}
}My apologies to Software Engineers worldwide for the code above. I know it’s not the best code you’ve seen but it works. I didn’t want to sacrifice readability for performance. I’m 400% sure there are better ways to write the code above so feel free to improve it. Heads up! You’ll have to forgive me again for the Play function in the next section that calls this expensive function A LOT per request. 😉
What the checkWin function does is relatively simple, we simply check if there is a winner by checking if any row, column or diagonal of the board has the same value. Now let’s create the makeMove function. Copy and add the code below to the pkg/logic.go file:
func makeMove(board *[][]int, player string) ([]int, error) {
var NoOpenSpotsError error
var openSpots [][]int
max := big.NewInt(100000000)
randInt, err := rand.Int(rand.Reader, max)
if err != nil {
return nil, NoOpenSpotsError
}
for i, row := range *board {
for j, cell := range row {
if cell == 0 {
openSpots = append(openSpots, []int{i, j})
}
}
}
if len(openSpots) == 0 {
return nil, NoOpenSpotsError
}
move := openSpots[randInt.Int64()%int64(len(openSpots))]
if player == "X" {
(*board)[move[0]][move[1]] = 2
} else {
(*board)[move[0]][move[1]] = 1
}
return move, nil
}We store all the open spots on the board in an array slice and then we pick a random spot from that array. We then update the board with the player’s move and return the move. If there are no open spots on the board, we return an error.
Now that we have the game logic, let’s create the API.
Creating the API
Let’s create a simple handler for the /play endpoint. Copy and paste the code below into the pkg/bot.go file:
package pkg
import (
"github.com/gofiber/fiber/v2"
)
type Game struct {
Board [][]int `json:"board"`
Player string `json:"player"`
GameOver bool `json:"game_over"`
}
func Play(c *fiber.Ctx) error {
var game Game
if err := c.BodyParser(&game); err != nil {
return err
}
if checkWin(game.Board) {
game.GameOver = true
return c.JSON(
fiber.Map{
"game_over": game.GameOver,
"move": nil,
},
)
}
move, err := makeMove(&game.Board, game.Player)
if err != nil {
game.GameOver = true
return c.JSON(
fiber.Map{
"game_over": game.GameOver,
"move": nil,
},
)
}
if checkWin(game.Board) {
game.GameOver = true
return c.JSON(
fiber.Map{
"game_over": game.GameOver,
"move": nil,
},
)
}
return c.JSON(
fiber.Map{
"game_over": game.GameOver,
"move": move,
},
)
}We start by creating a Game struct that holds the board, the player and a boolean that indicates if the game is over or not. We then parse the request body into the Game struct.
We then check if the game is over by calling the checkWin function we created earlier. If the game is over, we return a JSON response with the game_over field set to true and the move field set to nil. If the game is not over, we call the makeMove function we created earlier to make a move for the bot. We then check if the game is over again and handle it accordingly.
Finally, let’s hook up the handler to the API. Copy and paste the code below into the cmd/main.go file:
package main
import (
"server/pkg"
"github.com/gofiber/fiber/v2"
"github.com/gofiber/fiber/v2/middleware/cors"
"github.com/gofiber/fiber/v2/middleware/logger"
)
func main() {
// Create Go Fiber app
app := fiber.New()
app.Use(cors.New(cors.Config{
// Don't use AllowOrigins: "*" in production. It's insecure.
AllowOrigins: "*",
AllowHeaders: "Origin, Content-Type, Accept",
}))
app.Use(logger.New())
app.Get("/", func(c *fiber.Ctx) error {
return c.JSON(
fiber.Map{
"health": "ok",
},
)
})
app.Post("/play", pkg.Play)
// Start server on http://localhost:3000
app.Listen(":3000")
}We first created a new instance of the Fiber app and then set up cors and logger middleware to the app. We then created a simple handler for the `/` endpoint that returns a JSON response with the health field set to ok. Finally, we added the Play handler we created earlier to the `/play` endpoint.
You can now run the server by running the command below:
go run cmd/main.goIf all went well, You should see the following on your terminal:
The API is now ready so let’s move on to building the TUI. Time to get Rusty!
Building the TUI
We’ll be using the Ratatui library a lot in this section. Ratatui is the community-maintained fork of the original TUI library for Rust. It’s very easy to use with a lot of helpful widgets to get you up and running in no time. Let’s get started!
To make the code more modular and readable, we’ll be writing the tui-related code in separate files in the tui folder and then exposing the needed functions to the main.rs file through the src/tui/mod.rs file.
Add this code to the src/tui/mod.rs file:
pub mod entry;
pub mod game;
mod input;
mod ui;One more thing before we start writing the actual TUI code. We need to create the public Game struct that will be used to store the game state. Add the code below to the src/tui/game.rs file:
use serde::{Deserialize, Serialize};
#[derive(PartialEq, Eq, Serialize, Deserialize, Debug)]
pub enum Player {
X,
O,
}
#[derive(Serialize, Deserialize, Debug)]
pub struct Game {
pub board: Vec<Vec<u8>>,
pub player: Player,
pub game_over: bool,
}
impl Game {
pub fn new(player: Option<Player>, dim: usize) -> Game {
let rows = vec![0; dim];
let board = vec![rows; dim];
let player = player.unwrap_or(Player::X);
let game_over = false;
Game {
board,
player,
game_over,
}
}
}All we’ve done here is define a Serializable Player enum and Game struct with an initialization method that returns a new Game struct with the specified player (which defaults to “X”) and board dimension.
Let’s get to the tricky part! Building the TUI layout and handling user input.
Creating the Layout
Ratatui provides a lot of widgets that we can use to easily build our TUI interfaces. It uses the builder pattern to make it easy to chain methods and build complex layouts. We’ll start by working on the src/tui/ui.rs file.
To make things easier for you, my dear reader; I’m going to paste the code that goes into the src/tui/ui.rs file below and then explain what each section does. Remember to check out the GitHub repo for extensive documentation if you get stuck.
use std::io::{self, Stdout};
use ratatui::{
backend::CrosstermBackend,
layout::{Alignment, Constraint, Direction, Layout},
style::{Color, Style},
text::Text,
widgets::{Block, Borders, Cell, Paragraph, Row, Table},
Terminal,
};
use tui_input::Input;
use super::game::Game;
pub fn draw(
terminal: &mut Terminal<CrosstermBackend<Stdout>>,
input: &Input,
game: &Game,
) -> Result<(), io::Error> {
terminal.draw(|f| {
let chunks = Layout::default()
.direction(Direction::Vertical)
.margin(1)
.constraints(
[
Constraint::Percentage(5),
Constraint::Percentage(10),
Constraint::Percentage(70),
Constraint::Percentage(15),
]
.as_ref(),
)
.split(f.size());
let header = Block::default()
.title(String::from("Tic Rac Go!"))
.borders(Borders::NONE)
.title_alignment(Alignment::Center)
.style(Style::default().fg(Color::Yellow));
let input = Paragraph::new(input.value())
.style(Style::default())
.block(Block::default().borders(Borders::ALL).title("Input"));
let table_width = vec![Constraint::Length(5); game.board.len()];
let body = Table::new(game.board.iter().map(|row| {
Row::new(row.iter().map(|cell| {
match cell {
0 => Cell::from(Text::from("-"))
.style(Style::default().fg(Color::Green)),
1 => Cell::from(Text::from("X"))
.style(Style::default().fg(Color::Red)),
2 => Cell::from(Text::from("O"))
.style(Style::default().fg(Color::Blue)),
_ => panic!("Invalid cell value"),
}
}))
.height(2)
}))
.style(Style::default().fg(Color::White))
.header(
Row::new(vec![Cell::from(Text::from("Board"))])
.style(Style::default().fg(Color::Yellow))
.bottom_margin(1),
)
.widths(&table_width)
.column_spacing(1);
let footer = Paragraph::new(Text::from(
r"Press 'q' to quit, 'esc' to clear input, and 'enter' to submit your input eg 'A2'.",
))
.style(Style::default().fg(Color::Green))
.block(
Block::default()
.borders(Borders::ALL)
.title("Powered by Ratatui and Crossterm").border_style(
Style::default()
.fg(Color::Yellow)
)
);
f.render_widget(header, chunks[0]);
f.render_widget(input, chunks[1]);
f.render_widget(body, chunks[2]);
f.render_widget(footer, chunks[3]);
})?;
Ok(())
}After our imports, we define a draw function that takes a mutable reference to a Terminal instance, a reference to an Input instance, and a reference to a Game instance.
pub fn draw(
terminal: &mut Terminal<CrosstermBackend<Stdout>>,
input: &Input,
game: &Game,
) -> Result<(), io::Error> {
// ...
}Immediately after, we call the draw method on the Terminal instance that we passed into the draw function. Ratatui supports multiple backends but we’re using the CrosstermBackend backend in this tutorial. The draw method takes a closure that takes a mutable reference to a Frame instance. The Frame instance is used to render the widgets that we pass into the render_widget method at the function’s end.
pub fn draw(/* arguments */) /* returns */ {
terminal.draw(|f| {
// ...
f.render_widget(/* widget */, /* layout constraint */);
})?;
}For Ratatui to accurately render the widgets, we need to specify constraints for each widget. We do this by using the Layout struct. The Layout struct takes a Direction enum that specifies the direction of the layout. We’re using the Vertical variant. We also specify a margin of 1 for the layout.
And lastly, we specify how the Layout will be split up using the Constraint enum. We’re using the Percentage variant to specify the percentage of the terminal that each widget will take up. The split method returns a vector of Rect instances based on the Frame size that we can use to render the widgets.
let chunks = Layout::default()
.direction(Direction::Vertical)
.margin(1)
.constraints(
[
Constraint::Percentage(5),
Constraint::Percentage(10),
Constraint::Percentage(70),
Constraint::Percentage(15),
]
.as_ref(),
)
.split(f.size());The header, input, body and footer widgets defined afterwards all follow the same pattern so I won’t be discussing them too much. Here’s a quick summary of each widget:
- The header widget is a Block widget with the title “Tic Rac Go!” and a yellow foreground colour.
- The input widget is a Paragraph widget with a border and a title of “Input”.
- The body widget is a Table widget with a header of “Board” and a white foreground colour that renders the game board based on the board of the Game instance passed into the draw function.
- The footer widget is a Paragraph widget with a border and a title of “Powered by Ratatui and Crossterm”.
In the end, we render these widgets by passing them in chunks into the render_widget function.
This concludes the UI part of the tutorial. In the next section, we’ll be adding the logic to handle user input.
Handling Events and User Input
Similar to how the previous section was, I’m going to paste the code for the handle_input function and then explain it afterwards. Add this to the tui/input.rs file.
use std::io::{self, Stdout};
use crossterm::{
event::{self, DisableMouseCapture, Event, KeyCode},
execute,
terminal::{disable_raw_mode, LeaveAlternateScreen},
};
use ratatui::{backend::CrosstermBackend, Terminal};
use serde_json::Value;
use tui_input::{backend::crossterm::EventHandler, Input};
use super::game::{Game, Player};
pub fn handle_input(
terminal: &mut Terminal<CrosstermBackend<Stdout>>,
input: &mut Input,
game: &mut Game,
) -> Result<u8, io::Error> {
if let Event::Key(key) = event::read()? {
match key.code {
KeyCode::Char('q') => {
// restore terminal
disable_raw_mode()?;
execute!(
terminal.backend_mut(),
LeaveAlternateScreen,
DisableMouseCapture
)?;
terminal.show_cursor()?;
return Ok(1);
}
KeyCode::Enter => {
// Validate input
if input.value().len() != 2 {
input.reset();
return Ok(2);
}
let l = game.board.len() - 1;
let file_char = input.value().chars().next().unwrap();
let rank_char = input.value().chars().last().unwrap();
if !file_char.is_alphabetic() || !rank_char.is_digit(10) {
input.reset();
return Ok(2);
}
let r = (file_char as u8 - 'A' as u8) as usize;
let c = (rank_char as u8 - '1' as u8) as usize;
if r > l || c > l {
input.reset();
return Ok(2);
}
if game.board[r][c] != 0 {
input.reset();
return Ok(2);
}
if game.player == Player::X {
game.board[r][c] = 1;
} else {
game.board[r][c] = 2;
}
let serialized = serde_json::to_string(&game).unwrap();
let url = "http://localhost:3000/play";
let client = reqwest::blocking::Client::new();
let res = client
.post(url)
.body(serialized)
.header("Content-Type", "application/json")
.send()
.unwrap();
let res_str = res.text().unwrap();
let val: Value =
serde_json::from_str(&res_str.as_str()).unwrap();
match val["move"].clone() {
Value::Array(moves) => {
let r = moves[0].as_u64().unwrap() as usize;
let c = moves[1].as_u64().unwrap() as usize;
if game.player == Player::X {
game.board[r][c] = 2;
} else {
game.board[r][c] = 1;
}
}
_ => {}
}
game.game_over = val["game_over"].as_bool().unwrap();
input.reset();
}
KeyCode::Esc => {
input.reset();
}
_ => {
input.handle_event(&Event::Key(key));
}
}
}
Ok(0)
}The handle_input function has similar parameters as the draw function so let’s just move on to the function body and how the input is handled.
The cargo package that makes this possible is the `tui-input` crate. It provides an Input struct that can be used to get user input. It also provides an EventHandler struct that can be used to handle events like mouse events, key events, terminal focus events, etc.
if let Event::Key(key) = event::read()? {
match key.code {
// ...
}
}
Ok(0)Nothing fancy here. We’re just checking if the user has pressed a key and if so we’re matching on the key code. We’re using the EventHandler struct to handle key events only. Let’s go over the code in the handle_input function block by block.
match key.code {
KeyCode::Char('q') => {
// restore terminal
disable_raw_mode()?;
execute!(
terminal.backend_mut(),
LeaveAlternateScreen,
DisableMouseCapture
)?;
terminal.show_cursor()?;
return Ok(1);
}
KeyCode::Enter => {
// ...
}
KeyCode::Esc => {
input.reset();
}
_ => {
input.handle_event(&Event::Key(key));
}
}Looking at the match block above, we can see that if the user presses the `q` key, we restore the terminal state and return `1`. This is used to indicate that the user has pressed the `q` key and we should exit the program. If the user presses the `Esc` key, we reset the Input instance. This is used to clear the user input. If the user presses any other key, we pass the key to the Input instance to handle it.
I won’t talk about the sanity checks that validate that the user input is a valid cell e.g. “A1” or “C4” but I’ll start from where we send the game state to the backend. Now let’s break down what happens when the `Enter` key is pressed.
KeyCode::Enter => {
// -- Skipping Sanity checks --
let serialized = serde_json::to_string(&game).unwrap();
let url = "http://localhost:3000/play";
let client = reqwest::blocking::Client::new();
let res = client
.post(url)
.body(serialized)
.header("Content-Type", "application/json")
.send()
.unwrap();
let res_str = res.text().unwrap();
let val: Value =
serde_json::from_str(&res_str.as_str()).unwrap();
match val["move"].clone() {
Value::Array(moves) => {
let r = moves[0].as_u64().unwrap() as usize;
let c = moves[1].as_u64().unwrap() as usize;
if game.player == Player::X {
game.board[r][c] = 2;
} else {
game.board[r][c] = 1;
}
}
_ => {}
}
}All we do is send a blocking request with the serialized game struct to the server’s `/play` endpoint and we get a response back. The response is a JSON object that contains the next move and whether the game is over or not. We deserialize the response and update the game state accordingly.
Connecting to the API
In this final section, we’ll update the remaining two untouched files in the src directory. We’ll start with the tui/entry.rs file. Paste this code below:
use std::io;
use crossterm::{
event::{DisableMouseCapture, EnableMouseCapture},
execute,
terminal::{
disable_raw_mode, enable_raw_mode, EnterAlternateScreen,
LeaveAlternateScreen,
},
};
use ratatui::{backend::CrosstermBackend, Terminal};
use tui_input::Input;
use crate::Game;
use super::{input::handle_input, ui::draw};
pub fn terminal(game: &mut Game) -> Result<(), io::Error> {
let mut input = Input::default();
// setup terminal
enable_raw_mode()?;
let mut stdout = io::stdout();
execute!(stdout, EnterAlternateScreen, EnableMouseCapture)?;
let backend = CrosstermBackend::new(stdout);
let mut terminal = Terminal::new(backend)?;
terminal.clear()?;
loop {
if game.game_over {
// restore terminal
disable_raw_mode()?;
execute!(
terminal.backend_mut(),
LeaveAlternateScreen,
DisableMouseCapture
)?;
terminal.show_cursor()?;
println!("Game Over!");
break;
}
draw(&mut terminal, &input, &game).unwrap();
match handle_input(&mut terminal, &mut input, game).unwrap() {
1 => break,
2 => continue,
_ => (),
}
}
Ok(())
}This is the entry point to the whole TUI code. It has a single function called terminal that takes a mutable reference to a Game struct. This function setups our terminal and starts the main loop for handling user input and drawing the UI.
It breaks out of the loop only when the game is over or the user presses the `q` key. Let’s look at the main.rs file, which is the entry point to the entire program.
use crate::tui::entry::terminal;
use crate::tui::game::{Game, Player};
use std::io::{self, Error, ErrorKind};
pub mod tui;
use figlet_rs::FIGfont;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let stdin = io::stdin();
let standard_font = FIGfont::standard().unwrap();
let figure = standard_font.convert("Tic Rac Go!");
let mut game: Game;
let mut dimension = String::new();
let mut player = String::new();
clearscreen::clear().expect("failed to clear screen");
println!("{}", figure.unwrap());
println!("Enter Dimension (n x n), defaults to 3. n? ");
match stdin.read_line(&mut dimension) {
Ok(_) => {
match dimension.trim().parse::<u32>() {
Ok(i) => {
if i > 9 {
println!("Grid too large, defaulting to 3");
game = Game::new(None, 3);
} else {
game = Game::new(None, i as usize);
}
}
Err(..) => {
println!("Invalid input, defaulting to 3");
game = Game::new(None, 3);
}
};
}
Err(error) => {
print!("Error: {}, defaulting to 3", error);
game = Game::new(None, 3);
}
};
println!("Play as X or O? ");
match stdin.read_line(&mut player) {
Ok(_) => match (&player as &str).trim() {
"X" => game.player = Player::X,
"O" => game.player = Player::O,
_ => {
println!("Invalid input, defaulting to X");
game.player = Player::X;
}
},
Err(error) => {
print!("Error: {}, defaulting to X", error);
game.player = Player::X;
}
};
// Checking server health
let url = "http://localhost:3000/";
let resp = reqwest::blocking::get(url);
match resp {
Ok(_) => (),
Err(_) => {
return Err(Box::new(Error::new(
ErrorKind::ConnectionRefused,
format!("Server is not running at {}", url),
)));
}
}
terminal(&mut game)?;
Ok(())
}The main function is pretty straightforward. We first clear the screen and then take user input for the dimension of the board and the player’s choice of symbol and default to 3 and “X” respectively if the input is invalid.
After which, we check the health of the server and terminate the program if the server is not running. If the server is running, we call the terminal function in the tui/entry.rs file and pass it a mutable reference to the Game struct.
You can now run the program with the following command.
cargo runAnd you should see the following output.
Conclusion
Thanks for reading and making it this far. I hope you enjoyed this tutorial and learned something new. I’m sure there are many ways to improve this project and I encourage you to try it out.
I’m also open to any feedback, questions and suggestions. Feel free to reach out to me on Twitter or GitHub. Have a great day!
Resources and References
You can check out some of the resources listed below to learn more about the technologies used in this tutorial.
