cpoisson/rent-a-bot

Rentabot, your automation resources provider.

Rent-A-Bot

---

Rent-a-bot, your automation resource provider.

Exclusive access to a static resource is a common problem in automation, rent-a-bot allows you to abstract your resources and lock them to prevent any concurrent access.

Purpose

Rent-a-bot pursue the same objective as Jenkins Lockable Resource Plugin.

This latter works quite well, but only if you use... well... Jenkins.

Rent-A-Bot purpose is to fill the same needs in an environment where multiple automation applications exist.

e.g.

• Multiple Jenkins application servers
• Mixed automation application, gitlab CI + Jenkins
• Shared resources between humans and automates.

What is a resource?

A resource is defined by a name and the existence of a lock token indicating if the resource is locked.

Optional available fields help you customize you resources with additional information:

• Resource description
• Lock description
• Endpoint
• Tags

How to install and run

Clone the repository from GitLab or GitHub

git clone [email protected]:cpoisson/rent-a-bot.git

git clone [email protected]:cpoisson/rent-a-bot.git

Create a virtual env (here using virtualenv wrapper)

mkvirtualenv rent-a-bot
workon rent-a-bot

Install the package

pip install .   # pip install -e . if you want to install it in editable mode

Add Flask environment variables

export FLASK_APP=rentabot

export FLASK_DEBUG=true # If you need the debug mode

And... run!

flask run

How to use it

Alright, rent-a-bot is up and running.

At this stage you can connect to the front end at http://127.0.0.1:5000/ (assuming your flask app listen to the port 500)

You will notice that the resource list is empty (dang...), let's populate it

Populate the database

You will need a resource descriptor file to populate the database at startup.

RENTABOT_RESOURCE_DESCRIPTOR="/absolute/path/to/your/resource/descriptor.yml"

Resource descriptor

The resource descriptor is a YAML file. It's purpose is to declare the resources you want to make available on rent-a-bot

# Resources Description
# This file describes resources to populate in the database at rent-a-bot startup

coffee-machine:
    description: "Kitchen coffee machine"
    endpoint: "tcp://192.168.1.50"
    tags: "coffee kitchen food"

3d-printer-1:
    description: "Basement 3d printer 1"
    endpoint: "tcp://192.168.1.60"
    tags: "3d-printer basement tool"

another-resource:
    description: "yet another resource"
    endpoint: ""
    tags: ""

Once set, (re)start the flask application. The web view should be populated with your resources.

RestFul API

List resources

GET /api/v1.0/resources

e.g.

curl -X GET -i http://localhost:5000/rentabot/api/v1.0/resources

Access to a given resource

GET /api/v1.0/resources/{resource_id}

e.g.

curl -X GET -i http://localhost:5000/rentabot/api/v1.0/resources/2

Lock a resource

POST /api/v1.0/resources/{resource_id}/lock

e.g.

curl -X POST -i http://localhost:5000/rentabot/api/v1.0/resources/6/lock

Note: If the resource is available, a lock-token will be returned. Otherwise an error code is returned.

Lock a resource using it's resource id (rid), name (name) or tag (tag).

POST /api/v1.0/resources/lock

e.g.

curl -X POST -i http://localhost:5000/rentabot/api/v1.0/resources/lock\?rid\=6
curl -X POST -i http://localhost:5000/rentabot/api/v1.0/resources/lock\?name\=coffee-maker
curl -X POST -i http://localhost:5000/rentabot/api/v1.0/resources/lock\?tag\=coffee\&tag\=kitchen

Notes:

• If multiple available resources it the criteria, the first available will be returned.
• If criteria types are exclusive, resource id is prioritize over the name and tags, name is prioritize over tags.

Unlock a resource

POST /api/v1.0/resources/{resource_id}/unlock?lock-token={resource/lock/token}

curl -X POST -i http://localhost:5000/rentabot/api/v1.0/resources/6/unlock\?lock-token\={resource/lock/token}

Note: If the resource is already unlocked or the lock-token is not valid, an error code is returned.

How to tests

Tests implementation

Unit tests are done using py.test and coverage

How to run unit tests

python setup.py test

---

Helpful documentation used to design this application

• Designing a RESTful API with Python and Flask
• Testing Flask Applications
• Flask Project Template
• Flask SQLAlchemy
• Put versus Post
• Best practice for a pragmatic restful API
• Implementing a RESTful Web API with Python & Flask
• HTTP status code
• Implementing API Exceptions
• The Hitchhiker's Guide To Python

rent-a-bot's Issues

Potential race conditions on multi threaded server

I don't see a locking mechanism on database operations.

If I run flask in threaded mode with flask run --with-threads, I can produce race conditions:

• We enter in lock_by_id() 2 times, and it succeeds to lock both times (to reproduce easily, add a sleep on the db operations in controller lock_resource)
• The resource has been locked twice and only the second response lock-token is valid.

Suggestion: use threading.lock or sqlite locks to make the app thread-safe

lock resource by tag

User story

As an automation client
I want an api to lock a resource knowing it's name or tags
So That I can directly lock the type of resource knowing it's tags, name or id

Acceptance Criterias

One or Multiple resources available

Given one or multiple resources with one or multiple tags
And the resource(s) are available
When requesting a lock using one or multiple tags as criterias
Then A resource is locked and returned within the return informations (resource and lock token)

No resources available

Given one or multiple resources with one or multiple tags
And the resource(s) are not available
When requesting a lock using one or multiple tags as criterias
Then A 403 forbidden resource already locked answer must be returned

No tag(s) match the request

Given one or multiple resources with one or multiple tags
When requesting a lock using one or multiple other tags as criterias
Then A 404 resource not found MUST be returned