There are a lot of tutorials for creating bots on several programming languages and for a lot of web applications.
A bot is an autonomous piece of code, traveling the Internet executing one or more tasks. A couple of days ago I was creating from scratch a bot for @codesake to accomplish this task: listen the tweets for #scanwithdawn hashtag and capture the URL if given
After I started I found that my engine can be extensible enough to be used elsewhere.
Say hello to botolo.
It has been started as a just for fun project meanwhile I was collecting energies for working on dawn version 0.80.
I googled a bit to find something already cooked but I didn’t find anything feasible to me. The only code I found was the flamingo bot and I started looking at it for inspiration.
Basic features I need
The bot I need for dawn must:
- be able to authenticate to twitter
- be able to search for an hashtag
- capturing the tweet text
- looking for an url
- start a code review with dawn
- go to sleep
- iterate forever
This means that I must write a code that:
- uses a configuration file mainly for twitter secrets storage
- a basic task DSL to describe the action the bot must carry on and the schedule
- implement the logic of the actions
While working on the first bot version I realized that all the specific logic my codesake-dawn needs can be saved in a single ruby file meanwhile all the engine logic can be general enough to be reused in different bots.
That’s why I started the botolo project.
What a botolo bot is?
Before start talking about technical details, we must define what is a bot designed to be run using botolo.
A bot designed for botolo engine is a ruby file with all bot tasks
implementation and a YAML configuration file. In the YAML configuration file
there is the tasks list and their schedule.
Looking to venerable C programming language, you may think the YAML file is the .h include file defining function prototypes and the ruby file is the .c file containing functions’ implementation.
Botolo: configuration of a dummy bot
Botolo configuration is a per-bot YAML configuration file as said before. In the configuration file there are three main parts:
- bot: general information about the bot and also the name of the ruby behaviour file
- twitter: twitter secrets to be used by the bot to interact with this social network. As the time I’m writing this, botolo is able to run only bots interacting with twitter.
- task: this the list of all the routines the behaviour file must implement.
Let’s give a look to a basic YAML configuration file:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
This bot is named mydummy-bot, every ten minutes its task is descrived in the hello_world method you can find in the behaviour file that is mydummy-bot.rb. Botolo engine expects to find the behaviour file in the same config file directory, so there is no need to specify the ruby file at command line.
Botolo: the dummy bot behaviour
There is a single but critical rule in writing the bot behaviour. The class must be Botolo::Bot::Behaviour. I know, this breaks ruby naming convention if you named the file with your bot name.
I suggest you naming the config file with the name of your bot (and the YAML extension of course) and naming the behaviour file as behaviour.rb so you will keep safe ruby naming convention.
Another important rule is the class initialize method that it must accept an Hash parameter.
1 2 3
Following the aforementioned rules, our dummy_bot behaviour file is:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
It’s pretty simple to create a bot for the botolo engine, now let’s look at the engine internals.
Botolo: the engine initialization
Botolo engine initialization performs two major tasks:
- it reads the bot YAML file, building an hash with all configuration values
- it loads the behaviour file and creating an instance of Botolo::Bot::Behaviour
Embedded in the engine there is a dummy behaviour class performing no tasks but placed here just for sake of playing well in case of errors or missing filename.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
Reading configuration is nothing but a plain YAML parsing:
1 2 3 4
Botolo: the main loop
Botolo engine main loop: * iterates each task * check if the behaviour implements the action described in the YAML configuration and, if yes, running the action * going to sleep for the amount of seconds specified in the bot configuration
1 2 3 4 5 6 7 8 9 10 11 12 13
The codesake bot
codesake-bot is very easy to run with botolo.
1 2 3
Off by one
There is a major drawback in this first botolo implementation. It’s single threaded. With no parallelism, there is no chance in having actions executed at the same time. They must be executed each task per time, so the schedule time is not absolute to the bot start time but it’s relative to the previous task.
Next botolo versions will implement threads and parallelism between bot tasks.