Module buckets 

Hierarchical time buckets for post storage and discovery

Posts on hashiverse aren’t stored by post id — they are stored inside buckets keyed by (bucket_type, base_id, duration, bucket_time_millis), and every bucket deterministically hashes down to a single Id known as its location_id. That location_id is what the Kademlia DHT uses to decide which servers are responsible for holding the bucket.

Bucket types

BucketType picks what the bucket is about:

• User — posts authored by a specific client id
• Hashtag — posts tagged with a given hashtag id
• Mention — posts that mention a given client id
• ReplyToPost — replies to a specific parent post
• Sequel — long-running threads that continue from an earlier post

Duration hierarchy

BUCKET_DURATIONS is a coarse-to-fine ladder (year → month → week → day → 6h → 1h → 15m → 5m → 1m) chosen so that each level fans out ~4–6x into the next. When a bucket overflows at one granularity the client recurses into the finer granularity; the fan-out factor keeps the worst case from exploding into thousands of tiny buckets.

Sequel buckets start at year granularity (cheaper discoverability for long-lived threads); all other types start at month so that a single location_id isn’t responsible for a full year of heavy activity — see bucket_durations_for_type.

Types

• Bucket — a duration-only description of a bucket.
• BucketLocation — the full (bucket_type, base_id, duration, bucket_time_millis, location_id) tuple with deterministic hashing, self-verification via BucketLocation::validate, and a versioned tilde-delimited serialisation for use in HTML attributes and URLs.

Structs

Bucket

BucketLocation

Enums

BucketType

Constants

BUCKET_DURATIONS

These are the durations of the hierarchical buckets that posts will collect in. They are spaced such that there are always roughly 4-6 “more granular” buckets per “less granular” bucket. This ensures that no overflowed bucket would result in many tiny buckets needing to be scanned at the next level. Also make sure that the “less granular” bucket is a round multiple of its “more` granular” successor.

Functions

bucket_durations_for_type

Returns the appropriate bucket duration slice for a given bucket type. Sequel buckets start at year granularity for cheaper discoverability. All other bucket types start at month granularity so that a single location_id (set of servers) is not responsible for a year of potentially high activity.

generate_bucket_location