Add section on ID generation

1 files changed, 13 insertions, 0 deletions

diff --git a/README.md b/README.md
index 4ae11a7..07bd1ec 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,19 @@ All other files (such as html) are baked into the binary.
 It is planned to offer statically linked to musl versions in the future.
 This is possible thanks to the `diet` templates (inspired by pugjs) provided by vibe-d, which are computed at compile-time.
 
+### Stable IDs
+`brpaste` IDs are not the shortest.
+What they are, however, is stable.
+What does that mean?
+When you upload something to `brpaste`, the ID is generated through Murmurhash3 32 bit, and converted into a string of letters and symbols using base64.
+Murmurhash3 is suitable for lookups, so collision are sufficiently unlikely within the lifetime of your paste.
+However, if you upload the same paste twice, the ID will stay the same.
+The memory usage will not increase.
+This unlocks a few interesting use-cases (e.g not needing to keep around an open tab of a paste - just paste it again, you'll get the original link back).
+The bitsize of the ID is 32 bits, which translates to roughly 6 base64 "digits".
+This may not be the shortest, but it is short enough to memorize in one go (see: magic 7 of human working memory; approximated to more likely 6 if letters are involved).
+As such, the disadvantage is rather minimal, while the advantage is a nice-to-have, consistent, and cheap (murmurhash3 is fast, and there's no need to do things like keep a counter around).
+
 ### Other Utilities
 For server-side helpers and utilities (such as openrc scripts, systemd unit files, and anything else of the sort), see the `server/` directory.
 For client-side helpers and utilities (such as a `sprunge(1)`-like script, an `anypaste` plugin, and anything else of the sort), see the `client/` directory.