Improve desirable properties page

Author: RoyalIcing

lib/components_guide_web/templates/composable_systems/desirable-properties.html.md

@@ -1,22 +1,27 @@
 # Desirable Properties
 
-<h2>Values</h2>
+<h2 id=deterministic>Deterministic operations</h2>
 
-<h3 id=deterministic>Deterministic</h3>
-
-- A given input always produces the same output
-- Easily Cacheable
+- A given input will always produce the same output
+- Easily cacheable
 - Verifiable by multiple actors
-- *e.g. Multiply or adding two integers*
-- *e.g. Converting to lowercase or uppercase*
-- *e.g. Concatenating strings*
-- *e.g. Substring of another strings*
-- *e.g. Removing duplicates from a list of items*
-- *e.g. SHA256 hash digest (RFC 6234)*
-- *e.g. Base64 encoding/decoding (RFC 4648)*
-- *e.g. Gzip decoding (RFC 1952)*
-
-```console
+- Integers
+  - *e.g. Multiply two integers*
+  - *e.g. Adding two integers*
+  - *e.g. Finding the maximum of two integers*
+- Strings
+  - *e.g. Converting strings to lowercase or uppercase*
+  - *e.g. Concatenating strings*
+  - *e.g. Substring of another string*
+- List
+  - *e.g. Sorting a list of items*
+  - *e.g. Removing duplicates from a list of items*
+- Binary data
+  - *e.g. SHA256 hash digest (RFC 6234)*
+  - *e.g. Base64 decoding (RFC 4648)*
+  - *e.g. Gzip decoding (RFC 1952)*
+
+```bash
 # Converting to lowercase
 > echo "AbC" | tr "[:upper:]" "[:lower:]"
 abc
@@ -38,70 +43,72 @@ abc
 abc
 ```
 
-<h3 id=unique>Unique</h3>
+----
+
+<h2 id=unique>Unique values</h2>
 
-- Unique within a context or globally unique?
-- Won’t clash with existing values
+- Will never clash with existing values.
+- Choice: Unique within a context or globally unique?
+- Warning: just because a value is unique does not mean that it is unpredictable.
+- *e.g. Auto-incrementing SQL primary key*
+  - Con: might be predictable as it is _deterministic_.
 - *e.g. UUID (RFC 4122)*
 - *e.g. SHA256 hash digest (RFC 6234)*
-- Warning: could still be [guessable](#guessable): *e.g. Auto increment SQL primary key*
 
-```console
+```bash
 # UUID
 > uuidgen
 5F36D0E2-F524-46B8-870B-9AA70128F8AF
-```
-
-<h3 id=random>Random</h3>
 
-- Not [Guessable](#guessable)
-- Should never clash with existing values
-- *e.g. UUID v4*
-- *e.g. Cryptographically Random source*
-
-```console
-> head -c16 /dev/urandom | base64
-4mQ9EA==
-```
-
-<h3 id=guessable>Undesirable: Guessable</h3>
-
-- Not Secure
-- Not [Random](#random)
-- *e.g. Auto incrementing SQL primary key*
-- *e.g. The current time*
-
-```console
-> date -u '+%Y-%m-%dT%H:%M:%SZ'
-2021-02-07T22:51:21Z
+# Cryptographically random source
+> openssl rand -base64 20
+lrtijvqi3Dz4YrHZMQpcdfqTkJ4=
+
+# Auto-incrementing SQL primary key
+> sqlite3
+sqlite> create table items (id integer primary key);
+sqlite> insert into items values (?);
+sqlite> insert into items values (?);
+sqlite> insert into items values (?);
+sqlite> select id from items;
+1
+2
+3
+sqlite>
 ```
 
 ----
 
-<h2>Acts</h2>
-
-<h3 id=immutable>Immutable</h3>
+<h2 id=immutable>Immutable values</h2>
 
-- Changes to data work on a copy, preserving the original
-- Benefits caching: *given I have an object’s ID, the contents will always be the same*
-- Benefits syncing: *retrieve only the parts I do not yet have*
-- *e.g. Twitter tweets cannot be edited, only deleted*
-- *e.g. YouTube video media cannot be edited, only deleted*
-- *e.g. Git object from a committed file*
+- Can never be modified.
+- Changes to a data structure work on a copy, preserving the original.
+- Can help with caching: *given I have an resource’s ID, the contents will always be the same.*
+    - *e.g. Tweets on Twitter cannot be edited, only deleted.*
+    - *e.g. Uploaded videos on YouTube cannot be edited, only deleted.*
+- Can help with syncing: *retrieve only the values I do not yet have.*
+    - *e.g. Committed files in Git become immutable objects stored in `.git/objects/`.*
 
-<h3 id=stateless>Stateless</h3>
-
-- Is [Deterministic](#deterministic)
-- *e.g. Restful HTTP GET request*
+----
 
-<h3 id=idempotent>Idempotent</h3>
+<h2 id=idempotent>Idempotent operations</h2>
 
 - The same effect is produced if run once, twice, or a thousand times
+- *e.g. Adding an item to a set*
+- *e.g. Removing an item from a set*
+- *e.g. Sorting a list of items repeatedly*
+- *e.g. HTTP `PUT` request*
 - *e.g. Consumer of an at-least-once event delivery system*
 - *e.g. [Stripe charges](https://stripe.com/docs/api/idempotent_requests)*
-- Hint: Could generate a [random](#random) identifier for each request, which allows recording which commands have already been processed.
+- **Tip:** To get idempotent behavior, you could generate a [random](#random) identifier for each request, and have the receiver record which requests have been processed, and then skip whenever one is repeated.
+- See also: [Distributed Systems Shibboleths](https://jolynch.github.io/posts/distsys_shibboleths/)
+
+----
 
-<h3 id=versioned>Versioned</h3>
+<h2 id=versioned>Versioned operations</h2>
 
-- Won't break previous usages
+- Will allow a previously valid request to still work.
+- No breaking changes without the user opting into them.
+- This often relies on a **unique** version number.
+- *e.g. [Semantic Versioning](https://semver.org)*
 - *e.g. [Stripe’s API Versioning](https://stripe.com/blog/api-versioning)*

lib/components_guide_web/templates/composable_systems/index.html.eex

@@ -1,9 +1,7 @@
 <%= render view_module(@conn), "_header.html" %>
 
 <article>
-  <div class="text-white bg-gray-900">
-    <div class="content max-w-4xl mx-auto py-8 text-xl">
-      <%= render(view_module(@conn), @article <> ".html", conn: @conn) %>
-    </div>
+  <div class="prose md:prose-xl prose-invert max-w-4xl mx-auto py-16">
+    <%= render(view_module(@conn), @article <> ".html", conn: @conn) %>
   </div>
 </article>