Tổng quan
Tài liệu này xác định định dạng tệp I2P blockfile và các bảng trong hostsdb.blockfile được sử dụng bởi Blockfile Naming Service NAMING .
Blockfile cung cấp khả năng tra cứu Destination nhanh chóng trong định dạng nhỏ gọn. Mặc dù chi phí overhead của trang blockfile khá đáng kể, các destination được lưu trữ dưới dạng nhị phân thay vì Base 64 như trong định dạng hosts.txt. Ngoài ra, blockfile cung cấp khả năng lưu trữ metadata tùy ý (như ngày thêm, nguồn và bình luận) cho mỗi mục. Metadata này có thể được sử dụng trong tương lai để cung cấp các tính năng addressbook nâng cao. Yêu cầu lưu trữ của blockfile chỉ tăng nhẹ so với định dạng hosts.txt, và blockfile cung cấp thời gian tra cứu giảm khoảng 10 lần.
Một blockfile đơn giản là lưu trữ trên đĩa của nhiều bản đồ đã sắp xếp (các cặp khóa-giá trị), được triển khai như các skiplist. Định dạng blockfile được áp dụng từ Cơ sở dữ liệu Blockfile Metanotion METANOTION . Đầu tiên chúng ta sẽ định nghĩa định dạng tệp, sau đó là việc sử dụng định dạng đó bởi BlockfileNamingService.
Định dạng Blockfile
Đặc tả blockfile gốc đã được sửa đổi để thêm magic numbers vào mỗi trang. Tệp được cấu trúc thành các trang 1024-byte. Các trang được đánh số bắt đầu từ 1. “Superblock” luôn ở trang 1, tức là bắt đầu từ byte 0 trong tệp. Metaindex skiplist luôn ở trang 2, tức là bắt đầu từ byte 1024 trong tệp.
Tất cả các giá trị số nguyên 2-byte đều không có dấu. Tất cả các giá trị số nguyên 4-byte (số trang) đều có dấu và các giá trị âm là bất hợp pháp. Tất cả các giá trị số nguyên đều được lưu trữ theo thứ tự byte mạng (big endian).
Cơ sở dữ liệu được thiết kế để mở và truy cập bởi một luồng duy nhất. BlockfileNamingService cung cấp khả năng đồng bộ hóa.
Định dạng superblock
| Byte | Contents | Description |
|---|---|---|
| 0-5 | Magic number | 0x3141de493250 ("1A" 0xde "I2P") |
| 6 | Major version | 0x01 |
| 7 | Minor version | 0x02 |
| 8-15 | File length | Total length in bytes |
| 16-19 | First free list page | |
| 20-21 | Mounted flag | 0x01 = yes |
| 22-23 | Span size | Max number of key/value pairs per span (16 for hostsdb). Used for new skip lists. |
| 24-27 | Page size | As of version 1.2. Prior to 1.2, 1024 is assumed. |
| 28-1023 | unused |
| Byte | Contents | Description |
|---|---|---|
| 0-7 | Magic number | 0x536b69704c697374 "SkipList" |
| 8-11 | First span page | |
| 12-15 | First level page | |
| 16-19 | Size | Total number of keys - may only be valid at startup |
| 20-23 | Spans | Total number of spans - may only be valid at startup |
| 24-27 | Levels | Total number of levels - may only be valid at startup |
| 28-29 | Span size | As of version 1.2. Max number of key/value pairs per span. Prior to that, specified for all skiplists in the superblock. Used for new spans in this skip list. |
| 30-1023 | unused |
Tất cả các cấp độ đều có span. Không phải tất cả các span đều có cấp độ.
| Byte | Contents | Description |
|---|---|---|
| 0-7 | Magic number | 0x42534c6576656c73 "BSLevels" |
| 8-9 | Max height | |
| 10-11 | Current height | |
| 12-15 | Span page | |
| 16- | Next level pages | 'current height' entries, 4 bytes each, lowest first |
| remaining | unused |
Các cấu trúc key/value được sắp xếp theo key trong mỗi span và trên tất cả các span. Các cấu trúc key/value được sắp xếp theo key trong mỗi span. Các span khác ngoài span đầu tiên có thể không được để trống.
| Byte | Contents | Description |
|---|---|---|
| 0-3 | Magic number | 0x5370616e "Span" |
| 4-7 | First continuation page | or 0 |
| 8-11 | Previous span page | or 0 |
| 12-15 | Next span page | or 0 |
| 16-17 | Max keys | 16 for hostsdb |
| 18-19 | Size | Current number of keys |
| 20-1023 | key/value structures |
| Byte | Contents | Description |
|---|---|---|
| 0-3 | Magic number | 0x434f4e54 "CONT" |
| 4-7 | Next continuation page | or 0 |
| 8-1023 | key/value structures |
Độ dài key và value không được phân tách qua các trang, tức là tất cả 4 byte phải nằm trên cùng một trang. Nếu không có đủ chỗ thì 1-3 byte cuối cùng của trang sẽ không được sử dụng và độ dài sẽ được đặt tại offset 8 trong trang tiếp theo. Dữ liệu key và value có thể được phân tách qua các trang. Độ dài tối đa của key và value là 65535 byte.
| Byte | Contents |
|---|---|
| 0-1 | key length in bytes |
| 2-3 | value length in bytes |
| 4- | key data |
| value data |
| Byte | Contents | Description |
|---|---|---|
| 0-7 | Magic number | 0x2366724c69737423 "#frList#" |
| 8-11 | Next free list block | or 0 if none |
| 12-15 | Number of valid free pages | in this block (0 - 252) |
| 16-1023 | Free pages | 4 bytes each, only the first (valid number) are valid |
| Byte | Contents | Description |
|---|---|---|
| 0-7 | Magic number | 0x7e2146524545217e "~!FREE!~" |
| 8-1023 | unused |
Bảng Dịch vụ Đặt tên Blockfile
Các bảng được tạo và sử dụng bởi BlockfileNamingService như sau. Số lượng mục tối đa trên mỗi span là 16.
Properties Skiplist
%%__INFO__%% là skiplist cơ sở dữ liệu chính với các mục key/value String/Properties chỉ chứa một mục:
info - một Properties (UTF-8 String/String Map), được tuần tự hóa như một Mapping :
- version - “4”
- created - Thời gian Java long (ms)
- upgraded - Thời gian Java long (ms) (kể từ phiên bản cơ sở dữ liệu 2)
- lists - Danh sách cơ sở dữ liệu host được phân tách bằng dấu phẩy, sẽ được tìm kiếm theo thứ tự cho các truy vấn. Hầu như luôn là “privatehosts.txt,userhosts.txt,hosts.txt”.
- listversion_* - Phiên bản của từng cơ sở dữ liệu trong lists, ví dụ: listversion_hosts.txt=4. Được sử dụng để xác định việc nâng cấp một phần hoặc bị hủy bỏ của các danh sách riêng lẻ. (kể từ phiên bản cơ sở dữ liệu 4)
Reverse Lookup Skiplist
%%__REVERSE__%% là skiplist tra cứu ngược với các mục key/value Integer/Properties (từ phiên bản cơ sở dữ liệu 2):
- Các khóa skiplist là các số nguyên 4-byte, 4 byte đầu tiên của hash của Destination .
- Các giá trị skiplist mỗi cái là một Properties (một bản đồ String/String UTF-8) được tuần tự hóa như một Mapping
- Có thể có nhiều mục trong properties, mỗi mục là một ánh xạ ngược, vì có thể có nhiều hơn một hostname cho một destination đã cho, hoặc có thể xảy ra va chạm với cùng 4 byte đầu tiên của hash.
- Mỗi khóa property là một hostname.
- Mỗi giá trị property là chuỗi rỗng.
Danh sách bỏ qua hosts.txt, userhosts.txt, và privatehosts.txt
Đối với mỗi cơ sở dữ liệu host, có một skiplist chứa các host cho cơ sở dữ liệu đó. Lưu ý rằng định dạng phiên bản 4 hỗ trợ nhiều Destination cho mỗi hostname. Định dạng này được giới thiệu trong I2P phiên bản 0.9.26. Cơ sở dữ liệu phiên bản 3 được tự động di chuyển lên phiên bản 4.
Các key/value trong những skiplist này như sau:
key - một chuỗi UTF-8 (tên máy chủ)
value - - Database phiên bản 4: Một DestEntry, là một số byte đơn chỉ định số lượng cặp Properties/Destination sẽ theo sau. Số lượng cặp đó gồm: Một Properties (một Map UTF-8 String/String) được serialize dưới dạng Mapping theo sau bởi một Destination nhị phân (được serialize như thường lệ). - Database phiên bản 3: một DestEntry, là một Properties (một Map UTF-8 String/String) được serialize dưới dạng Mapping theo sau bởi một Destination nhị phân (được serialize như thường lệ).
Thuộc tính DestEntry thường chứa:
- “a” - Thời gian được thêm vào (Java long time tính bằng ms)
- “m” - Thời gian sửa đổi lần cuối (Java long time tính bằng ms)
- “notes” - Bình luận do người dùng cung cấp
- “s” - Nguồn gốc của mục nhập (thường là tên file hoặc URL đăng ký)
- “v” - Nếu chữ ký của mục nhập đã được xác minh, “true” hoặc “false”
Các khóa tên máy chủ được lưu trữ ở dạng chữ thường và luôn kết thúc bằng “.i2p”.