Forem: Rawley Fowler

Monitoring a Plack Application with SlapbirdAPM

Rawley Fowler — Fri, 16 May 2025 14:22:42 +0000

SlapbirdAPM is a free and open-source application performance monitoring (APM) platform specifically designed for Perl web applications. It provides developers with comprehensive observability tools to monitor and optimize their applications' performance.

SlapbirdAPM is easily installed on your Plack application, here is a minimal example, using a Dancer2 application:

Install with

cpan -I SlapbirdAPM::Agent::Plack

#!/usr/bin/env perl

use Dancer2;
use Plack::Builder;

get '/' => sub {
    'Hello World!';
};

builder {
    enable 'SlapbirdAPM';
    app;
};

Now, you can create an account on SlapbirdAPM, and create your application.

Then, simply copy the API key output and, add it to your application via the SLAPBIRDAPM_API_KEY environment variable. For example:

SLAPBIRDAPM_API_KEY=<API-KEY> plackup app.pl

or, you can pass your key in to the middleware:

builder {
    enable 'SlapbirdAPM', key => <YOUR API KEY>;
    ...
};

Now when you navigate to /, you will see it logged in your Slapbird dashboard!

SlapbirdAPM also supports DBI, meaning you can trace your queries, let's edit our application to include a few DBI queries:

#!/usr/bin/env perl

use Dancer2;
use DBI;
use Plack::Builder;

my $dbh = DBI->connect( 'dbi:SQLite:dbname=database.db', '', '' );

$dbh->do('create table if not exists users (id integer primary key, name varchar)');

get '/' => sub {
    send_as html => 'Hello World!';
};

get '/users/:id' => sub {
    my $user_id = route_parameters->get('id');
    my ($user) = 
        $dbh->selectall_array(
          'select * from users where id = ?',
          { Slice => {} }, $user_id );
    send_as JSON => $user;
};

post '/users' => sub {
    my $user_name = body_parameters->get('name');
    my ($user) =
      $dbh->selectall_array(
        'insert into users(name) values ( ? ) returning id, name',
        { Slice => {} }, $user_name );
    send_as JSON => $user;
};

builder {
    enable 'SlapbirdAPM';
    app;
};

Now we can use cURL to add data to our database:

curl -X POST -d 'name=bob' http://127.0.0.1:5000/users

Then, if we go back into Slapbird, we can view our timings for our queries:

This just breaks the surface of what is possible using SlapbirdAPM. You can also, generate reports, perform health-checks, and get notified if your application is creating too many 5XX responses.

Thanks for reading!

Introducing Humming-Bird v3

Rawley Fowler — Wed, 08 Nov 2023 01:41:51 +0000

Hey folks! It's been a while!

I've been busy, but I haven't forgotten about Humming-Bird. Actually I've been quite busy trying to figure out Web-Sockets, and swappable back-ends for Humming-Bird, features requested by many!

Web-Sockets have been put on the back-burner for a bit, but swappable back-ends, and many bug-fixes have been completed leading to a new version bump.

A lot has changed, and I'm excited to see what sort of back-ends the community may come up with.

To implement a Humming-Bird back-end, simply write a class that does Humming-Bird::Backend;, and implement the listen routine, with a single argument of a function that takes a Humming-Bird::Glue::Request and returns a Humming-Bird::Glue::Response:

use Humming-Bird::Glue;

unit role Humming-Bird::Backend::MyBackend;

method listen(&handler) {
    my $request  = Humming-Bird::Glue::Request.decode(somehow-get-http-request());
    my $response = &handler($request);
    somehow-send-http-response($response.encode);
}

Now in your Humming-Bird app add the following to the listen clause:

use Humming-Bird::Core;

get('/', -> $request, $response {
    $response.html("Hello World!");
});

listen(:backend(Humming-Bird::Backend::MyBackend));

Thanks for reading, Raku rocks!

Functional Programming with Raku

Rawley Fowler — Sun, 23 Apr 2023 18:36:52 +0000

Raku is a great language for functional programming, it has support for anonymous functions (blocks), partial application via assuming, and much more.

In this post I hope to outline how I use Raku as a functional (object-oriented) programming language similar to how I'd write a language like Scala.

The compose operator

In Raku o is an operator (a binary function). Which means we can compose two functions together to create a new one. This lets us build really cool abstractions over our functions. For example we can use it to create functions with hidden side-effects:

my $logger = -> $m { say $m; $m };
my $add-five = -> $x { $x + 5 };
my $add-five-and-log = $add-five o $logger;

say $add-five-and-log(25); # Prints 25, then prints 30

Note that the composition occurs backwards in a way, $add-five o $logger is equivalent to -> x { $add-five($logger(x)) }. Pretty neat right!

This also allows us to simply reduce arrays of functions into a single function, in the Humming-Bird source-code, you can see that in practice for "advice" the end-of-routing hooks:

method !add-route(Route:D $route, HTTPMethod:D $method --> Route:D) {
        my &advice = [o] @!advice;
        my &cb = $route.callback;
        my $r = $route.clone(path => $!root ~ $route.path,
                             middlewares => [|@!middlewares, |$route.middlewares],
                             callback => { &advice(&cb($^a, $^b)) });
        @!routes.push: $r;
        delegate-route($r, $method);
    }

This method on the Router class adds a route object to the context of the application, you'll notice the first line of the method, we apply o in a reduction to produce a single function from the advice array. @!advice being all the advice on this router. Advice are simply functions that take a response, and return a response. So you can imagine how the composition operator is layering all of them together like:

-> x { advice-four(advice-three(advice-two(advice-one(x)))) }

Then, to call the advice all we have to do is pass a response to the composition, and it will handle the rest.

Assuming

Assuming is a method derived from the Code class, and it allows us to perform partial-application on a function. Partial application is very simple, it means to call a function with less arguments than it requires, which in-turn returns a new function that contains the parameters you've already supplied. For example if we have an add function that takes two numbers, we could partially apply it like so:

my $add = -> $x, $y { $x + $y };

my $add-five = $add.assuming(5);

say $add-five(10); # prints 15
say $add-five(5); # prints 10

The result of calling .assuming(5) on the add function is a new function that looks like: -> $y { 5 + $y }.

This is a really neat feature that lets us create what I like to call 'stateless-state', meaning we can add state to our functions without actually exposing it to the consumer of the function.

A fairly complicated, yet elegant example of using .assuming in the wild is Humming-Birds middleware system:

my &composition = @!middlewares.map({ .assuming($req, $res) }).reduce(-> &a, &b { &a({ &b }) });
&composition(&!callback.assuming($req, $res))

We have to map all middleware to partially-apply the request and response objects that will be used throughout the request chain, then reduce to a single function that will take another function. Then finally, call the composition with the callback provided by the user. This is what allows middleware to have the $request, $response, &next parameters. Calling &next() is simply calling the next partially applied function in the chain!

Anonymous functions (blocks)

Raku is one of the only languages I know that has more than one way to declare an anonymous function (aka lambda). In Raku we have pointy-blocks (my favorite), normal blocks, WhateverCodes and anonymous sub-routines.

Typically, in my experience, you'll be fine with a normal block for most things, unless you want to strictly define your parameters, then it's best to use a pointy-block or anonymous sub-routine. If you need to explicitly return i.e short-circuit you'll probably want to use an anonymous sub, otherwise a pointy block will do.

Here's the same function add written using each type of block:

Normal block

my &add = { $^a + $^b };

Whatever Code

my &add = * + *;

Pointy block

my &add = -> $a, $b { $a + $b };

Anonymous sub

my &add = sub ($a, $b) { $a + $b };

You can use the & sigil to declare functions stored in variables in a more 'Raku-ish' way, this will tell other developers that the variable is a Callable.

You can pass these anonymous functions to other functions, this is used fairly-extensively in the realm of reactive-programming. whenever registers a callback with an anonymous function (block or pointy block):

react {
    whenever Supply.interval(1) -> $second {
        say 'Current second: $second';
    }
}

In Raku's standard library, for example, a for loop takes a block or point block as an argument, you probably never thought about it like that before right?

for [1,2,3,4] -> $x { say $x }; # That block can be thought of as a lambda!

In Humming-Bird when you declare routes like:

get('/', -> $request, $response {
   $response.write('Hello World!');
});

In the background that block is taken in by the get function then registered as what to call when the router receives a request.

Overall, Raku has some really interesting and usable functional patterns. I personally am a big fan of partial application and the composition operator. It is really fun as-well!

To finish off I'd like to leave a fun example, see if you can predict the result:

([o] [-> $a { $a + 1 }, -> $a { $a + 1 }])(2).say

Take care! Raku rocks!

How I Structure my Humming-Bird Projects

Rawley Fowler — Sun, 19 Mar 2023 23:45:30 +0000

Humming-Bird is a very unopinionated web framework. It allows the developer to structure their projects however they like. As the creator of Humming-Bird I can openly say that this was on purpose, and takes after a few other popular frameworks.

Though this was on purpose, it can seem daunting, especially to people new to the Raku ecosystem, or new to designing web-applications in general. I hope to underline the few structures I have employed to making sure my application makes sense from a developers point of view, but also from a Raku point of view.

The Single File Service

If you find that your service will be small, you may want to consider building your system in a single-file. This is done very simply with a structure like:

App-MyService/
    ├── bin/
    │   └── my-service
    ├── lib/
    │   └── App/
    │       └── MyService.rakumod
    ├── META6.json
    └── Dockerfile

In your META6.json you'll have:

...
    "provides": {
        "App::MyService": "lib/App/MyService.rakumod"
    }
...

Then in your bin file you'll want to import your service, and Humming-Bird, something like:

use Humming-Bird::Core;
use App::MyService;

listen(1234);

It is important that you import App::MyService after Humming-Bird::Core to avoid having some weird side-effects with route declarations in your service.

Model-View-Controller

Some web-apps would prefer to be elevated above the status of service, and would prefer to have a dynamic UI. This is typically done with the Model-View-Controller or MVC architecture. In a typical MVC application you separate concerns between the model, the view, and the controller by keeping them in separate name-spaces or folders.

With Humming-Bird, nothing really changes except that your views probably don't have to be individual Raku modules. I like to structure such applications like:

my-service/
    ├── templates/
    │   ├── foo.mustache
    │   └── bar.mustache
    ├── bin/
    │   └── my-service
    ├── lib/
    │   └── App/
    │       ├── MyService/
    │       │   ├── Controller/
    │       │   │   ├── Foo.rakumod
    │       │   │   └── Bar.rakumod
    │       │   └── Model/
    │       │       ├── User.rakumod
    │       │       ├── Friend.rakumod
    │       │       └── Post.rakumod
    │       └── MyService.rakumod
    ├── META6.json
    └── Dockerfile

You'll still want the same use statements in your bin file, but this time you'll have to do a provide in your META6 file for each of the nested modules.

...
"provides": {
    "App::MyService": "lib/App/MyService.rakumod",
    "App::MyService::Controller::Foo": "lib/App/MyService/Controller/Foo.rakumod"
    ...
},
...

Now you can layer your code nicely, having the controllers call to the models to get data, and then rendering pages based on your templates. In this example I used Template::Mustache by softmoth, but you can also user other templating languages like Template6 by the Raku Community, or RyML by the dashing tony-o.

Note: this is following an "Active-Record" approach to database management, where the sub-class of a type handles Repository type actions. You can use either. If you are looking for an "Active-Record" style database manager ORM thing, you can use Red.

Microservice

With a microservice I'm typically more focused around data and its flow, because of this, I adapt my single-file structure to also have a Repository section, allowing me to nicely package my database interactions. I also like to have a Queue or Communication module that handles talking with other service if I need to. This typically includes talking to queues, or establishing other UDP or TCP connections.

With Microservices I prefer the more fine-grained Repository approach where I can hone in on writing fast SQL vs the "Active-Record" approach that something like Red gives you. Because of this, I typically use DBIish for microservices.

My simple microservice structure typically looks like:

my-service/
    ├── bin/
    │   └── my-service
    ├── lib/
    │   └── App/
    │       ├── MyService/
    │       │   ├── Communication/
    │       │   │   ├── Queue.rakumod
    │       │   │   └── Upstream.rakumod
    │       │   ├── Repostiory/
    │       │   │   ├── Foo.rakumod
    │       │   │   └── Bar.rakumod
    │       │   └── Controller/
    │       │       ├── Foo.rakumod
    │       │       └── Bar.rakumod
    │       └── MyService.rakumod
    ├── META6.json
    └── Dockerfile

This blog post was fairly erratic, but I hope it demystified a little bit about project structure using Humming-Bird. I'm currently writing a small MVC example for Humming-Bird, make sure to check the examples directory to see some existing apps, and check back soon to see the full-fledged MVC example.

Thanks for reading, Raku rocks!

Practical Monads with Raku and Monad::Result

Rawley Fowler — Sun, 12 Mar 2023 16:21:08 +0000

Monads are a great tool in every programming language, they provide a simple way to hide side-effects in your code, and in languages that allow even the slightest amount of pattern matching, they enable "Railroad Oriented" programming.

Thankfully, Raku has given which enables us to perform simple pattern matching, and with it's dependent-type system we can easily define our own Monads. I wrote Monad::Result a month or two ago, and I have used it in almost all of my Raku projects since.

Simply install Monad::Result with zef:

zef install Monad-Result

Monad::Result is an extremely simple package that is designed to allow programmers to easily hide exceptions within a container, forcing the caller to evaluate both possible scenarios of the call. This is particularly useful when dealing with IO, Network calls, Databases, Asynchronous callbacks, etc. Basically anything with a well-defined side-effect. If you don't know what a side-effect is, it's basically the "sad-pass" of an operation. So in the case of an HTTP request, it may fail due to a number of reasons, it's failure would be it's side-effect. What's nice about using a Monad to represent this, is we can hide all the ugliness behind an easily consumed interface, whereas with exceptions it becomes quite cumbersome.

Abstracting away exceptions

The most common way I find myself using Monad::Result is with exceptions. Since I can't specify the exceptions in the type-signature, or return type of a function, I find they often go uncaught and lead to some gross bugs. But, with Monad::Result as the return type, the developer calling the code can infer "hey, this code might fail".

Here is a simple wrapper around DBIish I typically use to hide exceptions from the caller:

use DBIish;
use Monad::Result :subs;

my $db = DBIish.connect('SQLite', :database<foo.db>);

sub exec-sql(Str:D $sql, *@args --> Monad::Result:D) is export {
    CATCH {
        default {
            return error($_);
        }
    }

    my $stmt = db.prepare($sql); 
    ok($stmt.execute(|@args).allrows(:array-of-hash));
}

Let's break down what's going on inside the exec-sql sub-routine.

Since DBIish will fire an exception if something goes wrong, we catch it in the CATCH, it will catch any exception and return it as a Monad::Result{+Monad::Result::Error} basically a result of error, and obviously, if it succeeds, then the sub-routing will return a Monad::Result{+Monad::Result::Ok}, meaning it succeeded.

So if we wanted to use our new exec-sql sub-routing downstream we'll know explicitly that this call can, and will fail. So, we can do some pattern-matching with given to make sure our code is super safe!

Here is how you typically see a Monad::Result consumed:

given exec-sql('SELECT * FROM users') {
    when Monad::Result::Ok:D {
        my @users = $_.value; # safe to do so because we know we're Ok!
        say "Got all users! @users";
    }
    when Monad::Result::Error:D {
        my $exception = $_.error;
        warn "Failed to get all users, oh no! Had this error $exception";
    }
}

We simply match against the two possibilities for a Monad::Result, and our code remains completely safe.

Bind and Map

Now you're probably wondering "How the heck is this practical, what if I have to combine a hundred side-effect calls? This will become a mess!" And you'd be right, especially if Raku was a bad language that didn't allow user defined operators. (Just joking Go isn't bad, but Raku is simply better :^). Because of this, we can use the >>=: (Bind) and >>=? (Map) operators respectfully to manage our Monad.

These operators are super simple, all they do is take a Monad::Result on the left and a Callable on the right. Then, if the Monad::Result on the left is Ok, it will call the Callable with underlying value of the result. If the result isn't Ok, we just pass the error along. This allows for beautifully chained side-effects without the possibility of an exception blowing up on you (assuming you only call code that can't cause an exception). If you want to use another exception causing routing within a Bind or Map operation you'll have to write a wrapper that returns a Monad::Result instead.

exec-sql('SELECT * FROM users') >>=: { say @^a; ok(@^a.map(*.<name>)) };

This code will select all users from our database, if it succeeds we'll print to the console all of the users, and map the list to just their name.

We could also use the >>=? (Map) operation to avoid having to wrap our return with ok.

exec-sql('SELECT * FROM users') >>=? { say @^a; @^a.map(*.<name>) };

Now, if you're not really a Functional Programmer, these operators might be a little scary. Instead, if you wish, you can use the OO versions like so:

exec-sql('SELECT * FROM users').bind({ say @^a; ok(@^a.map(*.<name>)) });

and

exec-sql('SELECT * FROM users').map({ say @^a; @^a.map(*.<name>) });

Personally I like to use the OO version if I have to Bind or Map more than 3 times in a row.

Monads in the wild

Here are some snippets of some production code that uses Monad::Result

Find-one SQL

sub find-one($query, *@args) {
    exec-sql($query, |@args) >>=: -> @rows { @rows.elems == 1 ?? ok(@rows[0]) !! error(@rows) };
}

This is a simple wrapper around the earlier exec-sql routine that binds to it's result and if it isn't exactly one element it will return an Error result.

HTTP chaining

Note: This code isn't in production yet, but it's a part of a large project I'm working on :)

Another cool use for Monad::Result is for HTTP requests, sometimes we need to chain them together, here is a simple example of chaining 3 HTTP requests that rely on each-other:

auth-client.get-user-roles($id)
           .bind({ 'ADMIN' (elem) @^a ?? user-client.get-user($id) !! error('User is not an admin') })
           .bind({ dashboard-client.find-dashboard-by-user-id(@^a<id>) });

In this example, auth-client, user-client, and dashboard-client, are all wrappers around Cro::HTTP::Client that perform HTTP requests to different services. All of the end-points are abstracted by a function and return a Result::Monad, allowing the developers consuming them to simply chain them.

Conclusion

Monad::Result allows us to very concisely and elegantly deal with real-world side-effects. You can use them to simply chain side-effect reliant code without having to write a huge CATCH block, and they also give the developer consuming our code the chance to realize that the code may return an Error.

Monad::Result is not the only monad in the Raku ecosystem, there is also Definitely by Kay Rhodes (aka Masukomi) which provides a very nice "optional" type, that can fill a similar role to Monad::Result.

Thanks for reading, Raku Rocks!

Writing a Database backed Micro-service with Raku and Humming-Bird

Rawley Fowler — Sun, 05 Mar 2023 18:13:53 +0000

Earlier this year I built a web-application framework for Raku called Humming-Bird, it's come a long way since it's humble beginnings. In this post I'd like to outline how I use Humming-Bird to build fast, reliable, cloud-native services.

Getting set up

To begin, you'll want to make sure that you have Raku installed, I recommend using Rakubrew. Then we'll want to install Zef, if you're new to Raku, Zef is basically just NPM or CPAN for Raku, it's written by the fabulous Ugexe and is the default package manager people use with Raku. If you installed Raku with rakubrew download, you should already have it installed. If not, you can do rakubrew build-zef to install it for your current Raku install.

Finally, we'll want to install Humming-Bird, we can do this simply by running:

zef install Humming-Bird

This will pull the latest stable version of Humming-Bird.

Hello World

Now that we've installed all of the pre-requisites let's write a simple "Hello World" web application. Humming-Bird is really simple so there isn't much to it!

use Humming-Bird::Core;

get('/', -> $request, $response {
    $response.html('<h1>Hello World!</h1>');
});

listen(8080);

Now if we save this script as app.raku then run it with:

raku app.raku

We can navigate to http://localhost:8080 and we should see:

Let's break down what's going on here.

use Humming-Bird::Core;

Imports all of the exported members of Humming-Bird. This includes the functionality to allow creating routes, and to start the server.

get('/', -> $request, $response {
    $response.html('<h1>Hello World!</h1>');
});

We register a GET route on '/' and hookup a block, AKA anonymous function, AKA lambda, to handle it. This lambda must take a request, and a response, and returns a response. All of the methods provided by the response object implicitly return itself so it makes it easy to chain and return. Also, the last evaluated expression will become the return of the lambda.

listen(8080);

Starts a Humming-Bird::HTTPServer on port 8080.

Designing our service

Now that everything is setup and working. Let's get to designing our service. Our requirements are to design a service that provides the following end-points:

GET '/users': Returns all users in the database
POST '/users': Creates a new user in the database if it's valid
GET '/users/:id': Get's a user by their ID
DELETE '/users/:id': Delete's a user by their ID

Setting up the database

We'll also want a database for this, so we'll pull in the trusty DBIish module maintained by the Raku Community.

zef install DBIish

We're going to be using SQLite3 for this so make sure you have the necessary libs installed on your machine. On an Ubuntu box that would look like:

sudo apt-get install sqlite3 libsqlite3-dev

Now let's hook up DBIish into our existing code. We'll simply always run the create script for our table whenever the server starts, just to keep it fairly simple.

use DBIish;

my $db = DBIish.connect('SQLite', :database<user-db.sqlite3>);

$db.execute(q:to/SQL/);
CREATE TABLE IF NOT EXISTS user (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(20),
    age INTEGER,
    email VARCHAR
)
SQL

This code is fairly straight forward, but I'll break it down a little bit for people who haven't use DBIish before.

use DBIish;

my $db = DBIish.connect('SQLite', :database<user-db.sqlite3>);

First, we import DBIish then we assign a new variable $db to hold our connection, which is a SQLite3 connection, with filename user-db.sqlite3.

$db.execute(q:to/SQL/);
CREATE TABLE IF NOT EXISTS user (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(20),
    age INTEGER,
    email VARCHAR
)

Then, we try to create our table, note this will run every time we run this script. The whole q:to/SQL/ thing basically says: Read the following lines as a string until you read the end-sequence specified in between the /'s.

Overall our entire file looks like:

use Humming-Bird::Core;
use DBIish;

my $db = DBIish.connect('SQLite', :database<user-db.sqlite3>);

$db.execute(q:to/SQL/);
CREATE TABLE IF NOT EXISTS user (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(20),
    age INTEGER,
    email VARCHAR
)
SQL

get('/', -> $request, $response {
    $response.html('<h1>Hello World!</h1>')
});

listen(8080);

Setting up our end points

Now that our database is good to go, lets begin working on our endpoints, first up let's make an endpoint for getting all of the users.

We can express this simply as just returning the "jsonified" contents of our database. Humming-Bird depends on a module called JSON::Fast, we should import that too. Add:

use JSON::Fast;

to the top of our project to pull it in. It gives us access to the to-json and from-json sub-routines.

Getting all users

get('/users', -> $request, $response {
    my @user-rows = $db.execute('SELECT * FROM user').allrows(:array-of-hash);
    my $json = to-json(@user-rows);
    $response.json($json);
});

This will, select all of the users from the database as an array of hashes, then convert it to JSON with JSON::Fast's to-json, then send it with content-type JSON via $response.json.

Note: Humming-Bird doesn't really do any magic, the .json and .html methods are just wrappers for: .write($body, 'application/json') and .write($body, 'text/html') respectively. Write just writes a Buf or Str to the body of the response.

Creating a user

Now let's create a user with a POST request. This is really simple using $request.content, which will convert the JSON of the request to a Raku Hash for you.

sub validate-user(%user) {
    # I'll leave this up to you :^)
    %user<age> > 18;
}

post('/users', -> $request, $response {
    my %user = $request.content;
    if validate-user(%user) {
        $db.execute('INSERT INTO user (name, age, email) VALUES (?, ?, ?)', %user<name>, %user<age>, %user<email>);
        $response.status(201).json(to-json(%user));
    } else {
        $response.status(400).write('Bad Request :(');
    }
});

I'm letting you implement your own validation, so for now we just assume the user is valid unless their age is less than 18. Then we register our POST route, then we get the .content (which is a hash converted from the JSON body), then we validate, then if it's valid send a response with status 201 Created and write back the JSON that was sent to us. Otherwise send a bad-request response.

We can test this endpoint with:

curl -X POST -H "Content-Type: application/json" -d '{ "name": "bob", "age": 32, "email": "bob@gmail.com" }' http://localhost:8080/users

Now if we change the age to say 14, you should see a 400 Bad Request response:

curl -X POST -H "Content-Type: application/json" -d '{ "name": "bob", "age": 14, "email": "bob@gmail.com" }' http://localhost:8080/users

And finally if we check our database by browsing to http://localhost:8080/users we should see the user we created. In my case I ran the insert a few times.

Getting an individual user

This is a really simple end-point, the only difference between this and the getting all users is we have to get an ID from the request parameters.

get('/users/:id', -> $request, $response {
    my $id = $request.param('id');
    my @users = $db.execute('SELECT * FROM user WHERE id = ?', $id).allrows(:array-of-hash);

    return $response.status(404).html("User with id $id not found.") unless @users.elems == 1;

    $response.json(to-json(@users[0]));
});

Here we get the id from the requests parameters, specified in the route declaration, then we execute a DB query trying to find a user with that ID. If we don't get exactly one user back, we return a 404 Not Found status, otherwise we return a JSON response of the user we found.

If you navigate to http://localhost:8080/users/1 you should see a user you inserted (if not you'll need to insert some!)

Deleting a user

Another simple endpoint, this one will be very similar to the getting of a single user but instead we'll execute a DB delete then return nothing but a 204 No Content response.

delete('/users/:id', -> $request, $response {
    my $id = $request.param('id');

    try {
        CATCH { default { return $response.status(404).html("User with id $id not found.") } }
        $db.execute('DELETE FROM user WHERE id = ?', $id);
        $response.status(204);
    }
});

Major difference here is we use a try/catch block, you don't need to. Since Humming-Bird is functional I actually think it would be better practice to use a Monad type for handling errors something like Monad::Result,
but that's the beautiful part of Humming-Bird, it accommodates everyone's preferences.

Middleware

Well, your manager was so impressed that you finished this service in one-day that they decided to ask for a new feature! You should only be able to access the DELETE and POST routes if you have the magic passphrase of foobar in the X-AUTH header of your request.

Humming-Bird supports rich middleware development, using you guessed it, functions. So let's quickly write up our final middleware requirement.

sub auth-middleware($request, $response, &next) {
    without $request.header('X-AUTH') {
        return $response.status(401).write('unauthorized')
    }

    my $request-header = $request.header('X-AUTH');

    if $request-header ne 'foobar' {
        return $response.status(401).write('unauthorized');
    }

    &next();
}

A middleware is described as a function that takes a request, and a response, and finally a pointer to the next function in the middleware chain.

To register this middleware with a route, all we have to do is add it to the tail of the route delcaration like so:

delete('/users/:id', -> $request, $response {
    my $id = $request.param('id');

    try {
        CATCH { default { return $response.status(404).html("User with id $id not found.") } }
        $db.execute('DELETE FROM user WHERE id = ?', $id);
        $response.status(204);
    }
}, [ &auth-middleware ]); # Added auth middleware

Now if you hit either endpoint without an X-AUTH, or a non foobar X-AUTH header you will see a 401 Unauthorized screen. Otherwise, we'll slide on through to our end-points.

Final code

You can find the final code on github!

Conclusion

Humming-Bird makes it really easy to spin up all sorts of web-applications leveraging Raku's vibrant and welcoming ecosystem. If you're interested in deploying a service like this to production make sure you check out the docker example on github. Just like any application layer framework, Humming-Bird is NOT designed to face the internet directly, please reverse-proxy it with NGiNX or Apache2. If you have any questions, or find an issue with Humming-Bird please refer to the issue section on github.

Thanks for reading, Raku rocks!