whip 0.1

命令行界面

大多数功能都由whip-cli命令行工具提供。详细用法信息

$ whip-cli --help

将输入数据加载到my.db中（如有必要则创建它）

$ whip-cli --db my.db load input-file-1.json.gz input-file-2.json.gz

通过REST API提供数据库服务

$ whip-cli --db my.db serve

REST API也可以使用WSGI部署，例如使用gunicorn/nginx。

REST API

REST API支持以下查询：

• 获取IP地址的最新记录

  GET /ip/1.2.3.4

• 获取IP地址的特定记录

  GET /ip/1.2.3.4?datetime=2013-05-15

• 获取IP地址的完整历史记录

  GET /ip/1.2.3.4?datetime=all

在每种情况下，响应将是一个< span class="docutils literal">application/json编码的文档，即使没有找到匹配项，此时结果将是一个空的JSON文档。HTTP状态码仅用于表示错误。

输入数据格式

源文件格式很简单：它只是一个包含每行一个JSON格式文档的文本文件。每个文档可以包含关于一组IP地址的任意信息。

Whip本身需要三个字段

• begin：IP地址范围的起始（包含），例如1.0.0.0

• end：IP地址范围的结束（包含），例如1.0.255.255

• datetime：记录的时间戳，例如2013-02-28

除了这些字段外，每个文档还可以包含任意键/值对，例如"country"。

输入数据文件必须遵循以下规则：

• 文件中的每个范围必须至少跨越1个IP地址，但可以跨越任意数量的连续IP地址（不受网络块/CIDR限制），由begin和end字段指定。

• 单个输入文件中的范围不得重叠，但范围之间可以有间隙（在没有任何信息可用的情况下）。

• 单个输入文件中的范围必须按IP地址排序。IPv4范围必须在IPv6范围之前排序，因为Whip在内部使用RFC3493 IPv4映射IPv6地址。

• 在datetime字段中指定的时间戳应采用ISO8601格式，因为Whip依赖于输入字符串的字典序。

• 单个输入文件中的所有时间戳必须相同。是的，这增加了冗余，但避免了需要标题行或带外元数据的需求。

一个示例输入文档如下（为了清晰起见，格式化在多行中）

{
    "begin": "1.0.0.0",
    "end": "1.255.255.255",
    "datetime": "2013-02-28",
    "location": "Amsterdam",
    "some-other-data": "anything-you-like"
}

包含许多此类文档的单个输入文件如下所示

{"begin": "1.0.0.0", "end": "1.255.255.255", "datetime": "2013-02-28", "...": "..."}
{"begin": "2.0.0.0", "end": "2.255.255.255", "datetime": "2013-02-28", "...": "..."}
{"begin": "11.0.0.0", "end": "11.0.255.255", "datetime": "2013-02-28", "...": "..."}

Whip可以在单个加载过程中加载许多此类输入文件（例如，更长时期的每周快照）。