Get started

Install

Pre-required stuffs

• python3 , v3.5+ is required since bbox uses many async/await things
• etcd, the coordinate tools, v3+ is required

Download and install

% git clone https://github.com/haobtc/bbox.git
% cd bbox
# install aiobbox and dependencies, sudo privilege maybe required
% pip3 install .     

After the installation, a program called bbox should be available, by typing bbox there is a command list

% bbox
bbox - bixin micro services framework
usage: bbox <command> [args] [options]
commands
 init                      - generate ticket.json
 start <modspec> [modspec] - start rpc server
 httpd <modspec>           - start httpd and load module
 metrics                   - prometheus metrics url
 run <modspec> [modspec]   - run tasks
 rpc <srv::method> <arg> [arg] - trigger rpc request
 config <op> <arg> [arg]   - config operations
 cluster info              - print boxes in the cluster
 genkey <prefix>           - generate self-signed pkey and certs
 lock <name> [command]     - exec command after acquiring lock 

A simple example

Suppose we have a simple service called calc with a single method 'add2num' which returns argument one plus argument two

% cd ~/works      # indeed any path is ok
% mkdir calc
% cd calc
% bbox init       # init the project, create a ticket to the cluster
% ls
bbox.ticket.json
% cat bbox.ticket.json
{
  "bind_ip": "127.0.0.1",
  "etcd": [
    "127.0.0.1:2379"
  ],
  "language": "python3",
  "name": "calc",
  "prefix": "c3da3b5b84f840b2949690ae2afe2021"
}

the bbox.ticket.json has the necessary informations to enter a service cluster, it specifies

• etcd address list, etcd is the coordinator of a cluster, it must be started before a box runs
• bind_ip, the ip address box is bounded with, default is localhost
• prefix, the etcd key root to distinguish among different clusters, All boxes in a cluster MUST share the same prefix

Now let's start writing some code

# cat calc.py
from aiobbox.server import Service, ServiceError

srv = Service()
@srv.method('add2num')
async def add2num(request, a, b):
    return a + b
srv.register('calc')        # register a service named 'calc'

run it

% ls 
bbox.ticket.json	calc.py
# etcd should be started before
% bbox start calc
WARNING:root:box 3337b5d838594cd1a86260f96d1f1349 launched as 127.0.0.1:30268

Horry, it works! let's give the box a boxid

% bbox start calc --boxid calc001
WARNING:root:box calc001 launched as 127.0.0.1:30773

Now that a box runs, we can write a client or use command line tool to request this method

# bbox rpc emits JSONRPC requests and print result
% bbox rpc calc::add2num 2 4
{"error": null, "id": "fb9be6210c324570957592d68b2f3aa6", "result": 6}
% bbox cluster info
{
  "boxes": {
    "127.0.0.1:30773": {
      "bind": "127.0.0.1:30773",
      "boxid": "calc001",
      "services": [
        "calc"
      ]
    }
  },
  "etcd": [
    "127.0.0.1:2379"
  ],
  "prefix": "c3da3b5b84f840b2949690ae2afe2021"
}

Thus the example basically works! enjoy it.