diff options
Diffstat (limited to 'doc/index.html')
| -rw-r--r-- | doc/index.html | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..ed7f122 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,194 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="UTF-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <title>Clawflake</title> + <meta name="author" content="Nicolas Paul" /> + <meta name="description" content="A generation system with time-sortable keys." /> + <meta name="keywords" content="clawflake,discord,twitter,id,generator,specification,distributed" /> + <meta name="referrer" content="origin" /> + <meta name="theme-color" content="#dc8400" /> + <meta name="color-scheme" content="light dark" /> + <meta name="viewport" content="width=device-width,height=device-height,initial-scale=1.0,user-scalable=yes" /> + <meta name="creator" content="Nicolas Paul" /> + <meta name="googlebot" content="all" /> + <meta name="publisher" content="Nicolas Paul" /> + <meta name="robots" content="all" /> + <link rel="sitemap" href="/sitemap.xml" /> + <meta name="twitter:card" content="summary_large_image" /> + <meta name="twitter:site" content="@ncs_pl" /> + <meta name="twitter:creator" content="@ncs_pl" /> + <meta name="twitter:title" content="Clawflake" /> + <meta name="twitter:description" content="A generation system with time-sortable keys." /> + <meta property="og:title" content="Clawflake" /> + <meta property="og:type" content="website" /> + <meta property="og:url" content="https://staticgovanityurls.nicolaspl.com/" /> + <meta property="og:description" content="A generation system with time-sortable keys." /> + <meta property="og:determiner" content="" /> + <meta property="og:locale" content="en" /> + <meta property="og:site_name" content="Nicolas Paul" /> + <link rel="stylesheet" href="https://fashion-pepper.nicolaspl.com/css/fashion-pepper.css"> + <link rel="stylesheet" href="css/prism.css"> + <link rel="stylesheet" href="css/style.css"> + <script src="js/prism.js"></script> +</head> + +<body> + <header> + <nav> + <ul> + <li><strong>Clawflake</strong></li> + <li><a href="/">Home</a></li> + <li><a href="#license">License</a></li> + </ul> + </nav> + </header> + <main> + <h1 id="clawflake">Clawflake</h1> + <p>Clawflake is a distributed ID number generation system inspired from + <a href="https://github.com/twitter-archive/snowflake/tree/snowflake-2010"> + Twitter's Snowflake</a>. + </p> + + <p> The goal of Clawflake is to be hosted as a distributed system with + all workers being isolated from each others apart from the machine ID. + </p> + + <h2 id="format">Format</h2> + + <p> + Unlike Snowflake, the composition of a Clawflake uses all 64 bits. + </p> + + <table> + <thead> + <tr> + <th scope="col">#</th> + <th scope="col">Name</th> + <th scope="col">Bits</th> + <th scope="col">Description</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">1</th> + <td><code>time</code></td> + <td><code>45</code></td> + <td><code>The number of milliseconds passed from a configured epoch.</code></td> + </tr> + <tr> + <th scope="row">2</th> + <td><code>sequence</code></td> + <td><code>12</code></td> + <td><code>A sequence number rolling out whenever required.</code></td> + </tr> + <tr> + <th scope="row">3</th> + <td><code>machine</code></td> + <td><code>7</code></td> + <td><code>An identifier for the worker, between 0 and 127.</code></td> + </tr> + </tbody> + </table> + + <p> + Therefore, Clawflake ID numbers gives <mark>2<sup>45</sup> - 1 = 1115.7</mark> years + of safety from the configured epoch. + Thanks to the sequence number, a worker can handle <mark>2<sup>12</sup> = 4069</mark> + generations per milliseconds at peak. + The system can accept a maximum of <mark>2<sup>7</sup> = 128</mark> machines for a + given epoch. + </p> + + <cite> + Since Clawflake uses the most significant bit, converting a Clawflake ID + from <i>uint64</i> to <i>int64</i> is not safe. + </cite> + + <h2>Usage</h2> + + <p> + Before launching any worker, you need to determine the following + information: + + <ul> + <li><i>epoch</i>: corresponds to the epoch workers will be using to + generate IDs.</li> + <li><i>machine</i>: the identifier for the machine.</li> + </ul> + </p> + + <p> + Due to the format of a Clawflake, you can only have 128 workers (machine IDs + between 0 and 127). + </p> + + <p> + You can compile the worker by running the following command: + </p> + + <pre><code lang="language-bash"> + make generator + </code></pre> + + </p> + This will generate an executable named <code>generator</code> inside the + <code>bin</code> directory. + </p> + + <p> + You can then start the worker by running: + + <pre><code class="language-bash"> + export MACHINE_ID= # Worker ID, between 0 and 127 + export EPOCH= # Epoch to use in ID generation + ./bin/generator -machine_id=$MACHINE_ID -epoch=$EPOCH -grpc_host=":5000" + </code></pre> + </p> + + <p> + <strong>TIP:</strong> Use the flag <code>-help</code> to view the + documentation for the flags. + </p> + + <p> + A worker should be running on port <code>5000</code>. You can try generating some + Clawflake ID numbers using the + <a + href="https://github.com/n1c00o/clawflake/blob/master/api/nicolaspl/clawflake/generator/v3/generator.proto"> + Generator API + </a>. + </p> + + <p>A test client is available in <a + href="https://github.com/n1c00o/clawflake/blob/master/cmd/testclient/main.go">cmd/testclient/main.go</a>. + </p> + + <h2 id="license">License</h2> + <p> + Clawflake is governed by a BSD-style license that can be found in the + <a href="https://github.com/n1c00o/clawflake/blob/master/LICENSE"><code>LICENSE</code></a> file. + </p> + + <p> + The older codebase was licensed by the Apache License, Version 2.0, however + none of the old code still exists. + </p> + </main> + + <footer> + <hr /> + + <ul> + <li><a href="/">Website</a></li> + <li><a href="https://github.com/n1c00o/clawflake" target="_blank">Source</a></li> + <li><a href="https://nicolaspl.com" target="_blank">Nicolas Paul</a></li> + </ul> + + <p>© 2023</p> + </footer> +</body> + +</html>
\ No newline at end of file |