├── logo ├── logo.png └── logo.svg ├── .gitignore ├── Makefile ├── .github └── workflows │ ├── main.yml │ └── deploy.yml ├── src ├── test │ └── com │ │ └── yetanalytics │ │ ├── squuid │ │ ├── time_test.cljc │ │ └── uuid_test.cljc │ │ └── squuid_test.cljc └── main │ └── com │ └── yetanalytics │ ├── squuid │ ├── time.cljc │ └── uuid.cljc │ └── squuid.cljc ├── deps.edn ├── CHANGELOG.md ├── pom.xml ├── CONTRIBUTING.md ├── README.md ├── CODE_OF_CONDUCT.md └── LICENSE /logo/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yetanalytics/colossal-squuid/HEAD/logo/logo.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .calva/ 2 | .clj-kondo/.cache 3 | .cpcache/ 4 | .lsp/ 5 | .nrepl-port 6 | .cljs_node_repl/ 7 | cljs-test-runner-out/ 8 | target/ 9 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | .PHONY: clean test-clj test-cljs ci 2 | 3 | clean: 4 | rm -rf cljs-test-runner-out target 5 | 6 | test-clj: 7 | clojure -M:test:runner-clj 8 | 9 | test-cljs: 10 | clojure -M:test:runner-cljs 11 | 12 | ci: test-clj test-cljs 13 | 14 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: push 4 | 5 | jobs: 6 | test: 7 | runs-on: ubuntu-latest 8 | 9 | strategy: 10 | matrix: 11 | target: [test-clj, test-cljs] 12 | 13 | steps: 14 | - name: Checkout Repository 15 | uses: actions/checkout@v3 16 | 17 | - name: Setup CI Environment 18 | uses: yetanalytics/actions/setup-env@v0.0.4 19 | 20 | - name: Run make target ${{ matrix.target }} 21 | run: make ${{ matrix.target }} 22 | -------------------------------------------------------------------------------- /src/test/com/yetanalytics/squuid/time_test.cljc: -------------------------------------------------------------------------------- 1 | (ns com.yetanalytics.squuid.time-test 2 | (:require [clojure.test :refer [deftest testing is]] 3 | [com.yetanalytics.squuid.time :as t])) 4 | 5 | (deftest max-time-test 6 | (testing "before max time assertion" 7 | (is (<= #?(:clj (System/currentTimeMillis) 8 | :cljs (.now js/Date)) 9 | t/max-seconds)) 10 | (is (<= 0x0000FFFFFFFFFFFF t/max-seconds)) 11 | (is (not (<= 0x0001000000000001 t/max-seconds))))) 12 | 13 | (deftest before-test 14 | (testing "before? function" 15 | (let [curr-time (t/current-time)] 16 | (is (t/before? t/zero-time curr-time)) 17 | (is (not (t/before? curr-time t/zero-time))) 18 | (is (not (t/before? t/zero-time t/zero-time))) 19 | (is (not (t/before? curr-time curr-time)))))) 20 | -------------------------------------------------------------------------------- /deps.edn: -------------------------------------------------------------------------------- 1 | {:paths ["src/main"] 2 | :deps {org.clojure/clojure {:mvn/version "1.10.3"} 3 | org.clojure/clojurescript {:mvn/version "1.10.879"}} 4 | :aliases 5 | {:test 6 | {:extra-paths ["src/test"] 7 | :extra-deps {org.clojure/test.check 8 | {:mvn/version "1.0.0"} 9 | olical/cljs-test-runner 10 | {:mvn/version "3.8.0" 11 | :exclusions [org.clojure/clojurescript]} 12 | io.github.cognitect-labs/test-runner 13 | {:git/url "https://github.com/cognitect-labs/test-runner.git" 14 | :sha "2d69f33d7980c3353b246c28f72ffeafbd9f2fab"}}} 15 | :runner-clj 16 | {:main-opts ["-m" "cognitect.test-runner" 17 | "-d" "src/test"]} 18 | :runner-cljs 19 | {:main-opts ["-m" "cljs-test-runner.main" 20 | "-d" "src/test"]}}} 21 | -------------------------------------------------------------------------------- /.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: CD 2 | 3 | on: 4 | push: 5 | tags: 6 | - 'v*.*.*' # Enforce Semantic Versioning 7 | 8 | jobs: 9 | deploy: 10 | runs-on: ubuntu-latest 11 | 12 | steps: 13 | - name: Checkout repository 14 | uses: actions/checkout@v3 15 | 16 | - name: Setup CD Environment 17 | uses: yetanalytics/actions/setup-env@v0.0.4 18 | 19 | - name: Extract version 20 | id: version 21 | run: echo version=${GITHUB_REF#refs\/tags\/v} >> $GITHUB_OUTPUT 22 | 23 | - name: Build and deploy to Clojars 24 | uses: yetanalytics/actions/deploy-clojars@v0.0.4 25 | with: 26 | artifact-id: 'colossal-squuid' 27 | resource-dirs: '[]' 28 | version: ${{ steps.version.outputs.version }} 29 | clojars-username: ${{ secrets.CLOJARS_USERNAME }} 30 | clojars-deploy-token: ${{ secrets.CLOJARS_PASSWORD }} 31 | 32 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Change Log 2 | 3 | ## 0.1.5 4 | - Update GitHub CI and CD to remove deprecation warnings. 5 | 6 | ## 0.1.4 7 | 8 | - Update README by adding an API section. ([#16](https://github.com/yetanalytics/colossal-squuid/pull/16)) 9 | - Update CD workflow such that Clojars deployment occurs in a separate GitHub Action. ([#17](https://github.com/yetanalytics/colossal-squuid/pull/17)) 10 | - Add changelog, contributing guidelines, and code of conduct. ([#19](https://github.com/yetanalytics/colossal-squuid/pull/19)) 11 | - Add the `uuid->time` API function to extract the timestamp from a SQUUID. ([#18](https://github.com/yetanalytics/colossal-squuid/pull/18)) 12 | 13 | ## 0.1.3 14 | 15 | - Fix bug from 0.1.2 where JAR file is not compiled with the correct files. ([#15](https://github.com/yetanalytics/colossal-squuid/pull/15)) 16 | 17 | ## 0.1.2 18 | 19 | - Incorporate automatic Clojars deployment in CD workflow. ([#14](https://github.com/yetanalytics/colossal-squuid/pull/14), with ideas incorporated from [#13](https://github.com/yetanalytics/colossal-squuid/pull/13)) 20 | 21 | ## 0.1.1 22 | 23 | - Fix [issue](https://github.com/yetanalytics/colossal-squuid/issues/10) where strict monotonicity was not enforced on multiple threads. ([#11](https://github.com/yetanalytics/colossal-squuid/pull/11)) 24 | 25 | ## 0.1.0 26 | 27 | Initial release! 28 | -------------------------------------------------------------------------------- /src/main/com/yetanalytics/squuid/time.cljc: -------------------------------------------------------------------------------- 1 | (ns com.yetanalytics.squuid.time 2 | #?(:clj (:import [java.time Instant]))) 3 | 4 | (def ^:private max-time-emsg 5 | (str "Cannot generate SQUUID past August 2, 10889." 6 | " The timestamp would have exceeded 48 bits.")) 7 | 8 | (def max-seconds 9 | "The maximum underlying value of a 48-bit timestamp." 10 | 0x0000FFFFFFFFFFFF) 11 | 12 | (def zero-time 13 | "Return the timestamp corresponding to the beginning of the UNIX epoch, 14 | on Jan 1, 1970." 15 | #?(:clj Instant/EPOCH 16 | :cljs (js/Date. 0))) 17 | 18 | (defn current-time 19 | "Return the timestamp corresponding to the current system time." 20 | [] 21 | (let [curr-seconds #?(:clj (System/currentTimeMillis) 22 | :cljs (.now js/Date))] 23 | (assert (<= curr-seconds max-seconds) 24 | max-time-emsg) 25 | #?(:clj (Instant/ofEpochMilli curr-seconds) 26 | :cljs (js/Date. curr-seconds)))) 27 | 28 | (defn before? 29 | "Does `time1` occur strictly before `time2`?" 30 | #?(:clj ([^Instant time1 ^Instant time2] (.isBefore time1 time2)) 31 | :cljs ([time1 time2] (< time1 time2)))) 32 | 33 | #?(:clj 34 | (defn ms->Instant 35 | "Convenience function returning a java.time.Instant object 36 | given `ms` from the beginning of the UNIX epoch." 37 | [ms] 38 | (Instant/ofEpochMilli ms))) 39 | -------------------------------------------------------------------------------- /pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 4.0.0 5 | com.yetanalytics 6 | colossal-squuid 7 | jar 8 | 9 | UTF-8 10 | 1.8 11 | 1.8 12 | 13 | colossal-squuid 14 | A library for generating v8 sequential UUIDs 15 | https://github.com/yetanalytics/colossal-squuid 16 | 17 | 18 | Apache License, Version 2.0 19 | https://www.apache.org/licenses/LICENSE-2.0 20 | 21 | 22 | 23 | 24 | Kelvin Qian 25 | 26 | 27 | Milton Reder 28 | 29 | 30 | 31 | https://github.com/yetanalytics/colossal-squuid 32 | scm:git:git://github.com/yetanalytics/colossal-squuid.git 33 | scm:git:ssh://git@github.com/yetanalytics/colossal-squuid.git 34 | HEAD 35 | 36 | 37 | 38 | clojars 39 | Clojars repository 40 | https://clojars.org/repo 41 | 42 | 43 | 44 | 45 | clojars 46 | https://repo.clojars.org/ 47 | 48 | 49 | 50 | src/main 51 | 52 | 53 | -------------------------------------------------------------------------------- /src/test/com/yetanalytics/squuid/uuid_test.cljc: -------------------------------------------------------------------------------- 1 | (ns com.yetanalytics.squuid.uuid-test 2 | (:require [clojure.test :refer [deftest testing is are]] 3 | [com.yetanalytics.squuid.time :as t] 4 | [com.yetanalytics.squuid.uuid :as u])) 5 | 6 | (deftest inc-uuid-test 7 | (testing "incrementing UUIDs" 8 | (is (thrown-with-msg? 9 | #?(:clj clojure.lang.ExceptionInfo 10 | :cljs js/Error) 11 | #"Cannot increment UUID 00000000-0000-4fff-bfff-ffffffffffff any further." 12 | (u/inc-uuid #uuid "00000000-0000-4FFF-BFFF-FFFFFFFFFFFF"))) 13 | (are [u1 u2] (= u1 u2) 14 | #uuid "00000000-0000-0000-0000-000000000001" 15 | (u/inc-uuid u/zero-uuid) 16 | #uuid "12345678-1234-4234-8234-123456789ABD" 17 | (u/inc-uuid #uuid "12345678-1234-4234-8234-123456789ABC") 18 | #uuid "0000-0000-4000-8100-000000000000" 19 | (u/inc-uuid #uuid "00000000-0000-4000-80FF-FFFFFFFFFFFF") 20 | #uuid "00000000-0000-4000-8000-000000000010" 21 | (u/inc-uuid #uuid "00000000-0000-4000-8000-00000000000F") 22 | #uuid "00000000-0000-4000-8000-F00000000000" 23 | (u/inc-uuid #uuid "00000000-0000-4000-8000-EFFFFFFFFFFF") 24 | #uuid "00000000-0000-4000-8001-000000000000" 25 | (u/inc-uuid #uuid "00000000-0000-4000-8000-FFFFFFFFFFFF") 26 | #uuid "00000000-0000-4000-8100-000000000000" 27 | (u/inc-uuid #uuid "00000000-0000-4000-80FF-FFFFFFFFFFFF") 28 | #uuid "00000000-0000-4000-9000-000000000000" 29 | (u/inc-uuid #uuid "00000000-0000-4000-8FFF-FFFFFFFFFFFF") 30 | #uuid "00000000-0000-4001-8000-000000000000" 31 | (u/inc-uuid #uuid "00000000-0000-4000-BFFF-FFFFFFFFFFFF") 32 | #uuid "00000000-0000-4F00-8000-00000000000" 33 | (u/inc-uuid #uuid "00000000-0000-4EFF-BFFF-FFFFFFFFFFFF") 34 | #uuid "00000000-0000-4FFF-BFFF-FFFFFFFFFFFF" 35 | (u/inc-uuid #uuid "00000000-0000-4FFF-BFFF-FFFFFFFFFFFE")))) 36 | 37 | (deftest make-squuid-test 38 | (testing "making SQUUIDs" 39 | (is (= {:base-uuid u/zero-uuid ; Variant bits are not set 40 | :squuid #uuid "00000000-0000-8000-0000-000000000000"} 41 | (u/make-squuid t/zero-time u/zero-uuid))) 42 | (let [;; Timestamp has hex value of 0x17B41513496 43 | ts #inst "2021-08-13T21:00:46.102-00:00" 44 | id #uuid "0000-0000-4000-8100-12345678ABCD"] 45 | (is (= {:base-uuid id 46 | :squuid #uuid "017B4151-3496-8000-8100-12345678ABCD"} 47 | (u/make-squuid ts id)))))) 48 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Yet Analytics Open Source Contribution Guidelines 2 | 3 | ## Welcome to the Yet Analytics Open Source Community! 4 | 5 | Thank you for your interest in contributing to Yet Analytics Open Source projects. It is our goal in maintaining these Open Source projects to provide useful tools for the entire xAPI Community. We welcome feedback and contributions from users, stakeholders and engineers alike. 6 | 7 | The following document outlines the policies, methodology, and guidelines for contributing to our open source projects. 8 | 9 | ## Code of Conduct 10 | 11 | The Yet Analytics Open Source Community has a [Code of Conduct](CODE_OF_CONDUCT.md) which should be read and followed when contributing in any way. 12 | 13 | ## Issue Reporting 14 | 15 | Yet Analytics encourages users to contribute by reporting any issues or enhancement suggestions via [GitHub Issues](https://github.com/yetanalytics/lrsql/issues). 16 | 17 | Before submission, we encourage you to read through the existing [Documentation](doc/index.md) to ensure that the issue has not been addressed or explained. 18 | 19 | ### Issue Templates 20 | 21 | If the repository has an Issue Template, please follow the template as much as possible in your submission as this helps our team more quickly triage and understand the issues you are seeing or enhancements you are suggesting. 22 | 23 | ### Security Issues 24 | 25 | If you believe you have found a potential security issue in the codebase of a Yet Analytics project, please do NOT open an issue. Email [team@yetanalytics.com](mailto:team@yetanalytics.com) directly instead. 26 | 27 | ## Code Contributions 28 | 29 | ### Methodology 30 | 31 | For community contribution to the codebase of a Yet Analytics project we ask that you follow the [Fork and Pull](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) methodology for proposing changes. In short, this method requires you to do the following: 32 | 33 | - Fork the repository 34 | - Clone your Fork and perform the appropriate changes on a branch 35 | - Push the changes back to your Fork 36 | - Make sure your Fork is up to date with the latest `main` branch in the central repository (merge upstream changes) 37 | - Submit a Pull Request using your fork's branch 38 | 39 | The Yet Analytics team will then review the changes, and may make suggestions on GitHub before a final decision is made. The Yet team reviews Pull Requests regularly and we will be notified of its creation and all updates immediately. 40 | 41 | ### Style 42 | 43 | For contributions in Clojure, we would suggest you read this [Clojure Style Guide](https://github.com/bbatsov/clojure-style-guide) as it is one that we generally follow in our codebases. 44 | 45 | ### Tests 46 | 47 | In order for us to merge a Pull Request it must pass the `make ci` Makefile target. This target runs a set of unit, integration and/or conformance tests which verify the build's behavior. Please run this target and remediate any issues before submitting a Pull Request. 48 | 49 | We ask that when adding or changing functionality in the system that you examine whether it is a candidate for additional or modified test coverage and add it if so. You can see what sort of tests are in place currently by exploring the namespaces in `src/test`. 50 | 51 | ## License and Copyright 52 | 53 | By contributing to a Yet Analytics Open Source project you agree that your contributions will be licensed under its [Apache License 2.0](LICENSE). 54 | -------------------------------------------------------------------------------- /src/test/com/yetanalytics/squuid_test.cljc: -------------------------------------------------------------------------------- 1 | (ns com.yetanalytics.squuid-test 2 | #?@(:clj [(:require 3 | [clojure.test :refer [deftest testing is]] 4 | [clojure.spec.test.alpha :refer [check instrument]] 5 | [com.yetanalytics.squuid :as squuid] 6 | [com.yetanalytics.squuid.uuid :refer [compare-uuid]] 7 | [com.yetanalytics.squuid.time :as t])] 8 | :cljs [(:require 9 | [goog.math] 10 | [clojure.test.check] 11 | [clojure.test.check.properties] 12 | [cljs.test :refer [deftest testing is]] 13 | [cljs.spec.test.alpha] 14 | [com.yetanalytics.squuid :as squuid] 15 | [com.yetanalytics.squuid.uuid :refer [compare-uuid]] 16 | [com.yetanalytics.squuid.time :as t]) 17 | (:require-macros 18 | [cljs.spec.test.alpha :refer [check instrument]])])) 19 | 20 | (deftest squuid-gentest 21 | (testing "squuid gentests" 22 | (instrument [`squuid/generate-squuid* 23 | `squuid/generate-squuid 24 | `squuid/time->uuid 25 | `squuid/uuid->time]) 26 | (is (every? #(-> % :clojure.spec.test.check/ret :pass?) 27 | (check [`squuid/generate-squuid* 28 | `squuid/generate-squuid 29 | `squuid/time->uuid 30 | `squuid/uuid->time]))))) 31 | 32 | (deftest squuid-monotone-test 33 | (testing "squuid monotonicity" 34 | (is 35 | (loop [squuid-seq (repeatedly 10000 squuid/generate-squuid) 36 | squuid-seq' (rest squuid-seq)] 37 | (if (empty? squuid-seq') 38 | true 39 | (let [prev-squuid (first squuid-seq) 40 | next-squuid (first squuid-seq')] 41 | (if (neg-int? (compare-uuid prev-squuid next-squuid)) 42 | (recur squuid-seq' (rest squuid-seq')) 43 | false)))))) 44 | (testing "squuid monotonicity (sort)" 45 | (let [squuid-seq (repeatedly 1000 squuid/generate-squuid) 46 | squuid-seq' (sort (fn [u1 u2] (compare-uuid u1 u2)) squuid-seq)] 47 | (is (every? (fn [[u1 u2]] (zero? (compare-uuid u1 u2))) 48 | (map (fn [u1 u2] [u1 u2]) squuid-seq squuid-seq'))))) 49 | ;; Test for: https://github.com/yetanalytics/colossal-squuid/issues/10 50 | #?(:clj ; Rip cljs and its single thread. 51 | (testing "squuid monotonicity (multi-threaded)" 52 | (with-redefs [t/current-time #(java.time.Instant/ofEpochMilli 100)] 53 | (is (->> (fn [] 54 | (let [_ (squuid/reset-all!) 55 | [f1 f2] (pmap 56 | (fn [f] (future (f))) 57 | (repeat 2 squuid/generate-squuid)) 58 | max-1 (last (sort [@f1 @f2])) 59 | new-u (squuid/generate-squuid) 60 | max-2 (last (sort [max-1 new-u]))] 61 | [new-u max-2])) 62 | (repeatedly 30) 63 | (every? (partial apply =)))))))) 64 | 65 | (deftest time->uuid-test 66 | (testing "Matching #inst and #uuid" 67 | (let [uuid #uuid "017dfcad-ef95-8fff-8fff-ffffffffffff" 68 | inst #inst "2021-12-27T16:16:37.269Z"] 69 | (is (= uuid (squuid/time->uuid inst))))) 70 | (testing "input must be #inst" 71 | #?(:clj 72 | (is (thrown? Exception 73 | (squuid/time->uuid "2021-12-27T16:16:37.269Z"))) 74 | :cljs 75 | (is (thrown? js/Error 76 | (squuid/time->uuid "2021-12-27T16:16:37.269Z")))))) 77 | 78 | (deftest uuid->time-test 79 | (testing "confirm it matches with generate-squuid*" 80 | (is (let [id (squuid/generate-squuid*) 81 | time (squuid/uuid->time (:squuid id))] 82 | (= (:timestamp id) time)))) 83 | (testing "uuid->time and time->uuid are 'inverses'" 84 | (is (let [ts (t/current-time)] 85 | (= ts (-> ts squuid/time->uuid squuid/uuid->time))))) 86 | (testing "Matching #inst and #uuid" 87 | #?(:clj 88 | (let [uuid #uuid "017dfcad-ef95-8fff-8fff-ffffffffffff" 89 | inst #inst "2021-12-27T16:16:37.269Z" 90 | java-inst (t/ms->Instant (inst-ms inst))] 91 | (is (= java-inst (squuid/uuid->time uuid)))) 92 | :cljs 93 | (let [uuid #uuid "017dfcad-ef95-8fff-8fff-ffffffffffff" 94 | inst #inst "2021-12-27T16:16:37.269Z"] 95 | (is (= inst (squuid/uuid->time uuid)))))) 96 | (testing "input must be an uuid" 97 | #?(:clj 98 | (is (thrown? Exception (squuid/uuid->time "string uuid"))) 99 | :cljs 100 | (is (thrown? js/Error (squuid/uuid->time "string uuid")))))) 101 | -------------------------------------------------------------------------------- /src/main/com/yetanalytics/squuid.cljc: -------------------------------------------------------------------------------- 1 | (ns com.yetanalytics.squuid 2 | (:require [clojure.spec.alpha :as s] 3 | [com.yetanalytics.squuid.uuid :as u] 4 | [com.yetanalytics.squuid.time :as t] 5 | #?(:clj [clojure.spec.gen.alpha :as sgen]))) 6 | 7 | ;; This library generates sequential UUIDs, or SQUUIDs, based on the draft RFC 8 | ;; for v8 UUIDS: 9 | ;; https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format 10 | 11 | ;; The original approach of generating a 48-bit timestamp and merging it into 12 | ;; a v4 UUID is taken from the Laravel PHP library's orderedUuid function: 13 | ;; https://itnext.io/laravel-the-mysterious-ordered-uuid-29e7500b4f8 14 | 15 | ;; The idea of incrementing the least significant bit on a timestamp collision 16 | ;; is taken from the ULID specification: 17 | ;; https://github.com/ulid/spec 18 | 19 | (s/def ::base-uuid uuid?) 20 | (s/def ::squuid uuid?) 21 | (s/def ::timestamp 22 | #?(:clj (s/with-gen (partial instance? java.time.Instant) 23 | #(sgen/fmap (fn [ts] (t/ms->Instant (inst-ms ts))) 24 | (s/gen inst?))) 25 | :cljs (s/with-gen (partial instance? js/Date) 26 | #(s/gen inst?)))) 27 | 28 | ;; The atom is private so that only generate-squuid(*) can mutate it. 29 | ;; Note that merging Instant/EPOCH with v0 UUID returns the v0 UUID again. 30 | (def ^:private current-time-atom 31 | (atom {:timestamp t/zero-time 32 | :base-uuid u/zero-uuid 33 | :squuid u/zero-uuid})) 34 | 35 | (defn reset-all! 36 | "Reset such that the starting timestamp and UUIDs are zeroed out. This 37 | function is intended for use in development/testing." 38 | [] 39 | (reset! current-time-atom 40 | {:timestamp t/zero-time 41 | :base-uuid u/zero-uuid 42 | :squuid u/zero-uuid})) 43 | 44 | (s/fdef generate-squuid* 45 | :args (s/cat) 46 | :ret (s/keys :req-un [::base-uuid ::timestamp ::squuid])) 47 | 48 | (defn generate-squuid* 49 | "Return a map containing the following: 50 | :squuid The v8 sequential UUID made up of a base UUID and timestamp. 51 | :base-uuid The base v4 UUID that provides the lower 80 bits. 52 | :timestamp The timestamp that provides the higher 48 bits. 53 | 54 | See `generate-squuid` for more details." 55 | [] 56 | (let [ts (t/current-time)] 57 | (swap! current-time-atom 58 | (fn [m] 59 | (if (t/before? (:timestamp m) ts) 60 | (-> m 61 | (assoc :timestamp ts) 62 | (merge (u/make-squuid ts))) 63 | (-> m 64 | (update :base-uuid u/inc-uuid) 65 | (update :squuid u/inc-uuid))))))) 66 | 67 | (s/fdef generate-squuid 68 | :args (s/cat) 69 | :ret ::squuid) 70 | 71 | (defn generate-squuid 72 | "Return a new v8 sequential UUID, or SQUUID. The most significant 48 bits 73 | are created from a timestamp representing the current time, which always 74 | increments in value. The least significant 80 bits are derived from 75 | a base v4 UUID; since 6 bits are reserved (4 for the version and 2 for the 76 | variant), this leaves 74 random bits, allowing for about 18.9 sextillion 77 | random segments. 78 | 79 | The timestamp is coerced to millisecond resolution. Due to the 48 bit 80 | maximum on the timestamp, the latest time supported is August 2, 10889. 81 | 82 | In case that this function (or `generate-squuid*`) is called multiple times 83 | in the same millisecond, subsequent SQUUIDs are created by incrementing the 84 | base UUID and thus the random segment of the SQUUID. An exception is thrown 85 | in the unlikely case where all 74 random bits are 1s and incrementing can no 86 | longer occur." 87 | [] 88 | (:squuid (generate-squuid*))) 89 | 90 | (s/fdef time->uuid 91 | :args (s/cat :ts (s/and inst? #(<= 0 (inst-ms %) t/max-seconds))) 92 | :ret ::squuid) 93 | 94 | (defn time->uuid 95 | "Convert a timestamp to a UUID. The upper 48 bits represent 96 | the timestamp, while the lower 80 bits are fixed at 97 | `8FFF-8FFF-FFFFFFFFFFFF`." 98 | [ts] 99 | (assert (inst? ts)) 100 | (:squuid 101 | (u/make-squuid ts #uuid "00000000-0000-4FFF-8FFF-FFFFFFFFFFFF"))) 102 | 103 | (s/fdef uuid->time 104 | :args (s/cat :uuid ::squuid) 105 | :ret ::timestamp) 106 | 107 | (defn uuid->time 108 | "Convert a previously generated `uuid` to its corresponding timestamp. 109 | Returns a java.time.Instant object in Clojure, #inst in ClojureScript." 110 | [uuid] 111 | (assert (uuid? uuid)) 112 | #?(:clj 113 | (-> uuid 114 | (u/extract-ts-bytes) 115 | (t/ms->Instant)) 116 | :cljs 117 | (-> uuid 118 | (u/extract-ts-bytes) 119 | (js/Date.)))) 120 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # colossal-squuid 2 | 3 | Colossal Squuid Logo 4 | 5 | [![CI](https://github.com/yetanalytics/colossal-squuid/actions/workflows/main.yml/badge.svg)](https://github.com/yetanalytics/colossal-squuid/actions/workflows/main.yml) [![Clojars Project](https://img.shields.io/clojars/v/com.yetanalytics/colossal-squuid.svg)](https://clojars.org/com.yetanalytics/colossal-squuid) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-5e0b73.svg)](CODE_OF_CONDUCT.md) 6 | 7 | 8 | Library for generating Sequential UUIDs, or SQUUIDs. 9 | 10 | ## Overview 11 | 12 | A SQUUID is a Universally Unique Identifier, or UUID, whose value increases strictly monotonically over time. A SQUUID generated later will always have a higher value, both lexicographically and in terms of the underlying bits, than one generated earlier. This is in contrast to regular UUIDs (specifically version 4 UUIDs) that are completely random. However, it is also useful for generated SQUUIDs to maintain some degree of randomness to preserve uniqueness and reduce collision, rather than being completely one-to-one with a particular timestamp. 13 | 14 | ## Installation 15 | 16 | If using deps.edn, add the following line to your `:deps` map: 17 | ```clojure 18 | com.yetanalytics/colossal-squuid {:mvn/version "0.1.5"} 19 | ``` 20 | See the [Clojars page](https://clojars.org/com.yetanalytics/colossal-squuid) for how to install via Leiningen or other methods. 21 | 22 | **Note:** By default colossal-squuid will bring in the Clojure and ClojureScript libraries as transitive dependencies. If you wish to exclude these from your project (e.g. because it is clj or cljs-only), you can use the `:exclusions` keyword (which works for both [deps.edn](https://simonrobson.net/2019/04/16/clojure-deps-with-exclusions.html) and [Leiningen](https://github.com/technomancy/leiningen/blob/master/sample.project.clj#L55)): 23 | ```clojure 24 | :exclusions [org.clojure/clojure org.clojure/clojurescript] 25 | ``` 26 | 27 | For earlier releases, see the [Clojars page](https://clojars.org/com.yetanalytics/colossal-squuid), as well as the [changelog](CHANGELOG.md) for information about each release. 28 | 29 | ## API 30 | 31 | Four functions are provided in the `com.yetanalytics.squuid` namespace: 32 | - `generate-squuid` generates a SQUUID based off of a random base UUID and a timestamp representing the current time. 33 | - `generate-squuid*`, which returns a map containing the base UUID, the timestamp, and the SQUUID. 34 | - `time->uuid` takes a timestamp and creates a SQUUID with a fixed (not random) base UUID portion. 35 | - `uuid->time` takes a SQUUID and returns its corresponding timestamp. 36 | 37 | **Note:** `generate-squuid*` and `uuid->time` return timestamps as `java.time.Instant` instances in Clojure, `#inst` in ClojureScript. 38 | 39 | ```clojure 40 | (generate-squuid) 41 | ;; => #uuid "017de28f-5801-8c62-9ce9-cef70883794a" 42 | 43 | (generate-squuid*) 44 | ;; => {:timestamp #inst "2021-12-22T14:33:04.769000000-00:00" 45 | ;; :base-uuid #uuid "85335e1f-9c1f-4c62-9ce9-cef70883794a" 46 | ;; :squuid #uuid "017de28f-5801-8c62-9ce9-cef70883794a"} 47 | 48 | (time->uuid #inst "2021-12-22T14:33:04.769000000-00:00") 49 | ;; => #uuid "017de28f-5801-8fff-8fff-ffffffffffff" 50 | 51 | (uuid->time #uuid "017de28f-5801-8fff-8fff-ffffffffffff") 52 | ;; => #inst "2021-12-22T14:33:04.769000000-00:00" 53 | ``` 54 | 55 | ## Implementation 56 | 57 | Our solution is to generate SQUUIDs where the first 48 bits are timestamp-based, while the remaining 80 bits are derived from a v4 base UUID. Abiding by RFC 4122, there are 6 reserved bits in a v4 UUID: 4 for the version (set at `0100`) and 2 for the variant (set at `11`). This means that there are 74 remaining random bits, which allows for about 18.9 sextillion random segments. 58 | 59 | The timestamp is coerced to millisecond resolution. Specifically, it is the number of milliseconds since the start of the UNIX epoch on January 1, 1970. Due to the 48 bit maximum on the timestamp, the latest time supported is August 2, 10889; any millisecond-resolution timestamp generated after this date will have more than 48 bits. 60 | 61 | If two SQUUIDs are generated in the same milliseconds, then instead of using completely different base UUIDs, the earlier SQUUID will be incremented by 1 to create the later SQUUID, ensuring strict monotonicity. In the very unlikely case the SQUUID cannot be incremented, an exception will be thrown. 62 | 63 | The generated SQUUIDs have a version number of 8, as that is the version suggested by the draft RFC on SQUUIDs (see "Background"). 64 | 65 | A graphical representation of the generated SQUUIDs is as follows: 66 | ``` 67 | |-timestamp-| |----base v4 UUID----| 68 | xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx 69 | ``` 70 | Where `M` is the version (always set to `8`) and `N` is the variant (which, since only the two most significant bits are fixed, can range from `8` to `B`). 71 | 72 | ## Background 73 | 74 | - The original approach of generating a 48-bit timestamp and merging it into a v4 UUID is taken from the Laravel PHP library's `orderedUuid` function: https://itnext.io/laravel-the-mysterious-ordered-uuid-29e7500b4f8 75 | - The idea of incrementing the least significant bit on a timestamp collision is taken from the ULID specification: https://github.com/ulid/spec 76 | - The draft RFC for v8 UUIDs: https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format 77 | 78 | ## Contribution 79 | 80 | Before contributing to this project, please read the [Contribution Guidelines](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). 81 | 82 | ## License 83 | 84 | Copyright © 2021-2025 Yet Analytics, Inc. 85 | 86 | colossal-squuid is licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/yetanalytics/colossal-squuid/blob/main/LICENSE) for the full license text 87 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Yet Analytics Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | We as members, contributors, and leaders pledge to make participation in our 6 | community a harassment-free experience for everyone, regardless of age, body 7 | size, visible or invisible disability, ethnicity, sex characteristics, gender 8 | identity and expression, level of experience, education, socio-economic status, 9 | nationality, personal appearance, race, caste, color, religion, or sexual identity 10 | and orientation. 11 | 12 | We pledge to act and interact in ways that contribute to an open, welcoming, 13 | diverse, inclusive, and healthy community. 14 | 15 | ## Our Standards 16 | 17 | Examples of behavior that contributes to a positive environment for our 18 | community include: 19 | 20 | * Demonstrating empathy and kindness toward other people 21 | * Being respectful of differing opinions, viewpoints, and experiences 22 | * Giving and gracefully accepting constructive feedback 23 | * Accepting responsibility and apologizing to those affected by our mistakes, 24 | and learning from the experience 25 | * Focusing on what is best not just for us as individuals, but for the 26 | overall community 27 | 28 | Examples of unacceptable behavior include: 29 | 30 | * The use of sexualized language or imagery, and sexual attention or 31 | advances of any kind 32 | * Trolling, insulting or derogatory comments, and personal or political attacks 33 | * Public or private harassment 34 | * Publishing others' private information, such as a physical or email 35 | address, without their explicit permission 36 | * Other conduct which could reasonably be considered inappropriate in a 37 | professional setting 38 | 39 | ## Enforcement Responsibilities 40 | 41 | Community leaders are responsible for clarifying and enforcing our standards of 42 | acceptable behavior and will take appropriate and fair corrective action in 43 | response to any behavior that they deem inappropriate, threatening, offensive, 44 | or harmful. 45 | 46 | Community leaders have the right and responsibility to remove, edit, or reject 47 | comments, commits, code, wiki edits, issues, and other contributions that are 48 | not aligned to this Code of Conduct, and will communicate reasons for moderation 49 | decisions when appropriate. 50 | 51 | ## Scope 52 | 53 | This Code of Conduct applies within all community spaces, and also applies when 54 | an individual is officially representing the community in public spaces. 55 | Examples of representing our community include using an official e-mail address, 56 | posting via an official social media account, or acting as an appointed 57 | representative at an online or offline event. 58 | 59 | ## Enforcement 60 | 61 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 62 | reported to the community leaders responsible for enforcement at 63 | [team@yetanalytics.com](mailto:team@yetanalytics.com). 64 | All complaints will be reviewed and investigated promptly and fairly. 65 | 66 | All community leaders are obligated to respect the privacy and security of the 67 | reporter of any incident. 68 | 69 | ## Enforcement Guidelines 70 | 71 | Community leaders will follow these Community Impact Guidelines in determining 72 | the consequences for any action they deem in violation of this Code of Conduct: 73 | 74 | ### 1. Correction 75 | 76 | **Community Impact**: Use of inappropriate language or other behavior deemed 77 | unprofessional or unwelcome in the community. 78 | 79 | **Consequence**: A private, written warning from community leaders, providing 80 | clarity around the nature of the violation and an explanation of why the 81 | behavior was inappropriate. A public apology may be requested. 82 | 83 | ### 2. Warning 84 | 85 | **Community Impact**: A violation through a single incident or series 86 | of actions. 87 | 88 | **Consequence**: A warning with consequences for continued behavior. No 89 | interaction with the people involved, including unsolicited interaction with 90 | those enforcing the Code of Conduct, for a specified period of time. This 91 | includes avoiding interactions in community spaces as well as external channels 92 | like social media. Violating these terms may lead to a temporary or 93 | permanent ban. 94 | 95 | ### 3. Temporary Ban 96 | 97 | **Community Impact**: A serious violation of community standards, including 98 | sustained inappropriate behavior. 99 | 100 | **Consequence**: A temporary ban from any sort of interaction or public 101 | communication with the community for a specified period of time. No public or 102 | private interaction with the people involved, including unsolicited interaction 103 | with those enforcing the Code of Conduct, is allowed during this period. 104 | Violating these terms may lead to a permanent ban. 105 | 106 | ### 4. Permanent Ban 107 | 108 | **Community Impact**: Demonstrating a pattern of violation of community 109 | standards, including sustained inappropriate behavior, harassment of an 110 | individual, or aggression toward or disparagement of classes of individuals. 111 | 112 | **Consequence**: A permanent ban from any sort of public interaction within 113 | the community. 114 | 115 | ## Attribution 116 | 117 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], 118 | version 2.1, available at 119 | [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. 120 | 121 | Community Impact Guidelines were inspired by 122 | [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. 123 | 124 | For answers to common questions about this code of conduct, see the FAQ at 125 | [https://www.contributor-covenant.org/faq][FAQ]. Translations are available 126 | at [https://www.contributor-covenant.org/translations][translations]. 127 | 128 | [homepage]: https://www.contributor-covenant.org 129 | [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html 130 | [Mozilla CoC]: https://github.com/mozilla/diversity 131 | [FAQ]: https://www.contributor-covenant.org/faq 132 | [translations]: https://www.contributor-covenant.org/translations -------------------------------------------------------------------------------- /src/main/com/yetanalytics/squuid/uuid.cljc: -------------------------------------------------------------------------------- 1 | (ns com.yetanalytics.squuid.uuid 2 | #?(:clj (:import [java.util UUID]) 3 | :cljs (:require [clojure.string :refer [join]]))) 4 | 5 | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 6 | ;; Private constants 7 | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 8 | 9 | #?(:clj 10 | (def ^{:private true :const true} bit-mask-12 11 | (unchecked-long 0x0000000000000FFF))) 12 | 13 | #?(:clj 14 | (def ^{:private true :const true} bit-mask-16 15 | (unchecked-long 0x000000000000FFFF))) 16 | 17 | #?(:clj 18 | (def ^{:private true :const true} min-uuid-lsb 19 | (unchecked-long 0x8000000000000000))) 20 | 21 | #?(:clj 22 | (def ^{:private true :const true} max-uuid-lsb 23 | (unchecked-long 0xBFFFFFFFFFFFFFFF))) 24 | 25 | #?(:cljs 26 | (def ^:private bit-mask-16 (js/BigInt 0xFFFF))) 27 | 28 | #?(:cljs 29 | (def ^:private bit-shift-16 (js/BigInt 16))) 30 | 31 | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 32 | ;; Helper vars and functions 33 | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 34 | 35 | (def zero-uuid 36 | "The v0 UUID of all zeroes." 37 | #uuid "00000000-0000-0000-0000-000000000000") 38 | 39 | (defn rand-uuid 40 | "Generate a random v4 UUID." 41 | [] 42 | #?(:clj (UUID/randomUUID) 43 | :cljs (random-uuid))) 44 | 45 | (defn compare-uuid 46 | "Returns: 47 | - (< uuid1 uuid2): -1 48 | - (= uuid1 uuid2): 0 49 | - (> uuid1 uuid2): 1" 50 | [^UUID u1 ^UUID u2] 51 | #?(:clj 52 | (.compareTo u1 u2) 53 | :cljs 54 | (let [u1 (.toString u1) 55 | u2 (.toString u2)] 56 | (cond 57 | (< u1 u2) -1 58 | (= u1 u2) 0 59 | (> u1 u2) 1)))) 60 | 61 | (defn extract-ts-bytes 62 | "Extracts the first 48 bits of a SQUUID corresponding to a timestamp." 63 | [^UUID uuid] 64 | #?(:clj 65 | (-> (.getMostSignificantBits uuid) 66 | (bit-shift-right 16)) 67 | :cljs 68 | (let [s (str uuid)] 69 | (-> (str (subs s 0 8) (subs s 9 13)) 70 | (js/parseInt 16))))) 71 | 72 | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 73 | ;; Private helpers 74 | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 75 | 76 | (defn- throw-inc-uuid-error 77 | [u] 78 | (throw (ex-info (str "Cannot increment UUID " u " any further.") 79 | {:type ::exceeded-max-uuid-node 80 | :uuid u}))) 81 | 82 | (defn- throw-neg-timestamp 83 | [ts] 84 | (throw (ex-info (str "Timestamp " ts " occurs before January 1, 1970") 85 | {:type ::negative-timestamp 86 | :time ts}))) 87 | 88 | (defn- ts->num 89 | [ts] 90 | (let [ts-num (inst-ms ts)] 91 | (when-not (nat-int? ts-num) (throw-neg-timestamp ts)) 92 | ts-num)) 93 | 94 | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 95 | ;; Major functions 96 | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 97 | 98 | (defn inc-uuid 99 | "Increment the UUID by one bit. Throws an exception if there are no available 100 | bits left to increment." 101 | [^UUID u] 102 | #?(:clj ; Use bit operations 103 | (let [uuid-msb (.getMostSignificantBits u) 104 | uuid-lsb (.getLeastSignificantBits u)] 105 | (cond 106 | ;; least significant bits not maxed out 107 | ;; (Note that `<` isn't used since Java doesn't have unsigned ints) 108 | (not= uuid-lsb max-uuid-lsb) 109 | (UUID. uuid-msb (inc uuid-lsb)) 110 | ;; most significant bits not maxed out 111 | (not= (bit-and bit-mask-12 uuid-msb) bit-mask-12) 112 | (UUID. (inc uuid-msb) min-uuid-lsb) 113 | ;; oh no 114 | :else 115 | (throw-inc-uuid-error u))) 116 | 117 | :cljs ; Use string operations 118 | (let [u-char-arr (js/Array.from (.toString u)) 119 | inc-char (fn [c] (.toString (inc (js/parseInt c 16)) 16)) 120 | ret-uuid (fn [char-arr] (UUID. (join char-arr) nil))] 121 | (loop [i 35] ; start from the back and inch forwards 122 | (cond 123 | ;; Regular hexes: 0x0 to 0xF 124 | (or (< 23 i) 125 | (< 19 i 23) 126 | (< 14 i 18)) 127 | (let [c (aget u-char-arr i)] 128 | (if (or (identical? "F" c) (identical? "f" c)) 129 | (do (aset u-char-arr i "0") 130 | (recur (dec i))) 131 | (do (aset u-char-arr i (inc-char c)) 132 | (ret-uuid u-char-arr)))) 133 | 134 | ;; Variant hexes: 0x0 to 0xB 135 | (= 19 i) 136 | (let [c (aget u-char-arr i)] 137 | (if (or (identical? "B" c) (identical? "b" c)) 138 | (do (aset u-char-arr i "8") 139 | (recur (dec i))) 140 | (do (aset u-char-arr i (inc-char c)) 141 | (ret-uuid u-char-arr)))) 142 | 143 | ;; Dashes: ignore 144 | (#{18 23} i) 145 | (recur (dec i)) 146 | 147 | :else 148 | (throw-inc-uuid-error u)))))) 149 | 150 | (defn make-squuid 151 | "Make a new v8 sequential UUID. Uses `uuid` as the base UUID if provided; 152 | otherwise uses a random v4 UUID as the base. Returns a map containing 153 | `:base-uuid` and `:squuid`." 154 | ([ts] 155 | (make-squuid ts (rand-uuid))) 156 | ([ts ^UUID u] 157 | #?(:clj ; Use bit operations 158 | (let [;; Timestamp 159 | ts-long (ts->num ts) 160 | ;; Base UUID 161 | uuid-msb (.getMostSignificantBits u) 162 | uuid-lsb (.getLeastSignificantBits u) 163 | ;; Putting it all together (and change version from v4 to v8) 164 | uuid-msb' (-> (bit-or (bit-shift-left ts-long 16) 165 | (bit-and bit-mask-16 uuid-msb)) 166 | (bit-clear 14) 167 | (bit-set 15)) 168 | squuid (UUID. uuid-msb' uuid-lsb)] 169 | {:base-uuid u 170 | :squuid squuid}) 171 | 172 | :cljs ; Use string operations 173 | (let [make-padding 174 | (fn [max-len s] (join (repeat (- max-len (count s)) "0"))) 175 | ;; Timestamp manips 176 | ts' (js/BigInt (ts->num ts)) 177 | ts-hi (bit-shift-right ts' bit-shift-16) 178 | ts-lo (bit-and ts' bit-mask-16) 179 | ts-hs (.toString ts-hi 16) 180 | ts-ls (.toString ts-lo 16) 181 | ts-hp (make-padding 8 ts-hs) 182 | ts-lp (make-padding 4 ts-ls) 183 | ;; Base UUID manips 184 | u-str (subs (.toString u) 15) 185 | ;; Cook some SQUUID 186 | raw-squuid (str ts-hp ts-hs 187 | "-" 188 | ts-lp ts-ls 189 | "-" 190 | "8" u-str) 191 | cooked-squuid (UUID. raw-squuid nil)] 192 | {:base-uuid u 193 | :squuid cooked-squuid})))) 194 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /logo/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 481 | --------------------------------------------------------------------------------