Merge branch 'playfulprogramming:main' into main

Author: taylor-shift

Diff for: content/crutchcorn/posts/uuid-v6-8/UUIDv6.svg

@@ -0,0 +1,92 @@
+---
+{
+    title: "UUIDv6, UUIDv7, and UUIDv8; what are they?",
+    description: "There's new UUIDs on the block! Let's explore what's new with UUIDv6, v7, and v8.",
+    published: '2024-11-20T21:52:59.284Z',
+    tags: ['computer science'],
+    license: 'cc-by-4',
+    collection: "Explaining UUIDs",
+    order: 3
+}
+---
+
+[In our first article explaining what UUIDs are](/posts/what-are-uuids), we explored a few different variants of UUID:
+
+- [UUIDv1](/posts/what-are-uuids#UUIDv1)
+  - A machine's network card information + a timestamp
+- [UUIDv2](/posts/what-are-uuids#UUIDv2)
+  - [It's a long story.](/posts/what-happened-to-uuid-v2)
+- [UUIDv3](/posts/what-are-uuids#UUIDv3and5)
+  - Encode a string using MD5
+- [UUIDv4](/posts/what-are-uuids#UUIDv4)
+  - Random UUID with effectively zero chance of producing the same number twice
+- [UUIDv5](/posts/what-are-uuids#UUIDv3and5)
+  - UUIDv3 but more secure (uses SHA-1)
+
+Since that time, however, there [was an RFC that was accepted](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html) which added 3 new standard UUID types:
+
+- [UUIDv6](#UUIDv6)
+  - UUIDv1 but better for database indexes
+- [UUIDv7](#UUIDv7)
+  - UUIDv1 without network card information and with a more standard timestamp
+- [UUIDv8](#UUIDv8)
+  - An intentionally broad UUID spec for all non-standard UUIDs - make up your own UUIDs
+
+Let's explore each of these UUID systems individually to understand them better.
+
+
+
+# Create a Database Index with UUIDv6 {#UUIDv6}
+
+If you've worked much with UUIDv1 UUIDs, you'll see a pattern in the new UUIDv6 mechanism. If we look at the UUIDv1 example:
+
+![A UUID broken down into "Low Time", a dash, "Mid Time", a dash, "Version", "High Time", a dash, "Variant", "Clock", a dash, and finally a "MAC Address". An example UUIDv1 might be "4e2b4d4c-92e8-11ed-86a8-3fdb0085247e"](../what-are-uuids/UUIDv1.svg)
+
+And compare it to the UUIDv6 example:
+
+![A UUID broken down into "Time High", a dash, "Time Mid", a dash, "Version", "Time Low", a dash, "Variant", "Clock", a dash, and finally a "MAC Address". An example UUIDv6 might be "1ed92e84-e2b4-6d4c-86a8-3fdb0085247e"](./UUIDv6.svg)
+
+We can see how the order of the UUIDv6 is "just" a rearrangement of the bytes presented in a UUIDv1.
+
+Why is this?
+
+Well, this reorder allows multiple UUIDs to be sorted without having to parse them more in-depth. This helps makes databases of UUIDv6s easier to index as opposed to UUIDv1s while retaining the same base information.
+
+> [Read more about the specifics of UUIDv6's sorting improvements in their draft RFC.](https://ietf-wg-uuidrev.github.io/rfc4122bis/draft-00/draft-ietf-uuidrev-rfc4122bis.html#section-6.10)
+
+**Why UUIDv6?**
+
+This is useful if your projects are already using UUIDv1 and you need a drop-in replacement with better database indexing.
+
+**Why not UUIDv6?**
+
+[According to the RFC that introduces v6, v7, and v8](https://ietf-wg-uuidrev.github.io/rfc4122bis/draft-00/draft-ietf-uuidrev-rfc4122bis.html#name-uuid-version-6): 
+
+> Systems that do not involve legacy UUIDv1 SHOULD consider using UUIDv7 instead.
+
+Let's explore why that is by taking a look at UUIDv7 next.
+
+# More Standard Timestamps with UUIDv7 {#UUIDv7}
+
+If we look at the byte order of UUIDv7 without any additional context, it might start to look familiar to UUIDv1 and v6:
+
+![A UUID broken down into "Time High", a dash, "Time Mid", a dash, "Version", "Random", a dash, "Variant", "Random", a dash, and finally "Random". An example UUIDv7 might be "0185aa25-112e-7cc3-98c4-dc0c0c07398f"](./UUIDv7.svg)
+
+However, if we note the `input data` section of this graph, the distinction becomes clear.
+
+While UUIDv1, v6, and v7 all track time; v1 and v6 use "a count of 100- nanosecond intervals since 00:00:00.00, 15 October 1582" as their time-keeping mechanism.
+
+Compare and contrast that to UUIDv7 utilizing the far more standard ["Epoch time", or, "Unix time"](https://en.wikipedia.org/wiki/Unix_time).
+
+See, Epoch time is broadly used in nearly every computer system that needs to keep track of time. This makes v7 the superior choice over v6 and v1 for most usages, since encoding and decoding date logic becomes far more standardized.
+
+# Make your own UUID rules with UUIDv8 {#UUIDv8}
+
+Now comes the fun one of the bunch of new UUID formats: UUIDv8.
+
+![A UUID broken down into "Custom", a dash, "Custom", a dash, "Version", "Custom, a dash, "Variant", "Custom", a dash, and finally "Custom". An example UUIDv8 might be "01234567-89ab-8cde-8f01-23456789abcd"](./UUIDv8.svg)
+
+You'll notice that outside of the encoded variant and version that UUIDv8 allows you to encode any data you'd like.
+
+This is mostly useful for future-proofing UUIDs for the foreseeable future. By allowing whatever format you want as a formalized UUID standard,
+vendors (like APIs, databases, and more) can make their own flavors of UUIDs that extend the v8 format for their own needs.

Diff for: content/crutchcorn/posts/uuid-v6-8/UUIDv7.svg

@@ -63,6 +63,7 @@
 		"@types/hast": "^3.0.4",
 		"@types/html-escaper": "^3.0.0",
 		"@types/json5": "^2.2.0",
+		"@types/lru-cache": "^7.10.10",
 		"@types/mdast": "^4.0.3",
 		"@types/node": "^20.5.0",
 		"@types/uuid": "^10.0.0",
@@ -96,6 +97,7 @@
 		"junk": "^4.0.1",
 		"lint-staged": "^15.2.7",
 		"live-server": "^1.2.2",
+		"lru-cache": "^11.0.2",
 		"msw": "^2.3.5",
 		"npm-run-all": "^4.1.5",
 		"octokit": "^4.0.2",

Diff for: content/crutchcorn/posts/uuid-v6-8/UUIDv8.svg

@@ -1,21 +1,34 @@
 import { Element, Root } from "hast";
 import { fromHtml } from "hast-util-from-html";
 import { find } from "unist-util-find";
+import { LRUCache } from "lru-cache";
+
+export async function fetchAsBrowser(input: string | URL, init?: RequestInit) {
+	const response = await fetch(input, {
+		...init,
+		headers: {
+			"User-Agent":
+				"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
+			"Accept-Language": "en",
+			...init?.headers,
+		},
+	});
+	const isSuccess = `${response.status}`.startsWith("2");
+	if (!isSuccess)
+		throw new Error(`Request ${input} returned an error: ${response.status}`);
+	return response;
+}
 
-const pageHtmlMap = new Map<string, Promise<Root | null>>();
+const pageHtmlCache = new LRUCache<string, Promise<Root | null>>({
+	max: 50,
+});
 
 export function fetchPageHtml(src: string): Promise<Root | null> {
-	if (pageHtmlMap.has(src)) return pageHtmlMap.get(src)!;
+	if (pageHtmlCache.has(src)) return pageHtmlCache.get(src)!;
 
 	const promise = (async () => {
-		const srcHTML = await fetch(src, {
-			headers: {
-				"User-Agent":
-					"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
-				"Accept-Language": "en",
-			},
-		})
-			.then((r) => (r.status === 200 ? r.text() : undefined))
+		const srcHTML = await fetchAsBrowser(src)
+			.then(async (r) => await r.text())
 			.catch(() => null);
 
 		// if fetch fails...
@@ -26,7 +39,7 @@ export function fetchPageHtml(src: string): Promise<Root | null> {
 		return srcHast;
 	})();
 
-	pageHtmlMap.set(src, promise);
+	pageHtmlCache.set(src, promise);
 	return promise;
 }
 

Diff for: content/crutchcorn/posts/uuid-v6-8/index.md

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const copyFiles = async (srcDir: string, destDir: string) => {
+	await fs.promises.mkdir(destDir, { recursive: true });
 	const readDir = await fs.promises.readdir(srcDir);
 
 	await Promise.all(

Diff for: package.json

@@ -13,6 +13,7 @@ export interface IFramePlaceholderProps {
 	propsToPreserve: string;
 	pageTitle: string;
 	pageIcon: string;
+	pageIconFallback: string;
 }
 
 /** @jsxImportSource hastscript */
@@ -35,6 +36,9 @@ export function IFramePlaceholder({
 						decoding="async"
 						data-nozoom="true"
 						data-dont-round="true"
+						{...{
+							onerror: `this.src='${props.pageIconFallback}';this.onerror='';`,
+						}}
 					/>
 				</div>
 				<div class="embed__header__info">

Diff for: pnpm-lock.yaml

@@ -5,7 +5,6 @@ import { Plugin } from "unified";
 import { visit } from "unist-util-visit";
 
 import { EMBED_MIN_HEIGHT, EMBED_SIZE } from "../constants";
-import { fromHtml } from "hast-util-from-html";
 import { find } from "unist-util-find";
 import { getLargestManifestIcon } from "../../get-largest-manifest-icon";
 import { IFramePlaceholder } from "./iframe-placeholder";
@@ -15,36 +14,43 @@ import * as stream from "stream";
 import sharp from "sharp";
 import * as svgo from "svgo";
 import { fetchPageHtml, getPageTitle } from "utils/fetch-page-html";
+import { LRUCache } from "lru-cache";
 
 interface RehypeUnicornIFrameClickToRunProps {
 	srcReplacements?: Array<(val: string, root: VFile) => string>;
 }
 
 // default icon, used if a frame's favicon cannot be resolved
-const defaultPageIcon = "/link.png";
+const defaultPageIcon = "/icons/website.svg";
 
 function getIconPath(src: URL) {
 	return `generated/${src.hostname}.favicon`;
 }
 
 // Cache the fetch *promises* - so that only one request per manifest/icon is processed,
 //   and multiple fetchPageInfo() calls can await the same icon
-const pageIconMap = new Map<string, Promise<string>>();
+const pageIconCache = new LRUCache<string, Promise<string>>({
+	max: 50,
+});
+
 function fetchPageIcon(src: URL, srcHast: Root): Promise<string> {
-	if (pageIconMap.has(src.hostname)) return pageIconMap.get(src.hostname)!;
+	if (pageIconCache.has(src.hostname)) return pageIconCache.get(src.hostname)!;
 
 	const promise = (async () => {
 		const iconPath = getIconPath(src);
-		const iconDir = await fs.promises
-			.readdir(path.dirname(iconPath))
+		const iconDir = path.dirname("public/" + iconPath);
+		await fs.promises.mkdir(iconDir, { recursive: true });
+
+		const existingIconFiles = await fs.promises
+			.readdir(iconDir)
 			.catch(() => []);
 
 		// If an icon has already been downloaded for the origin (in a previous build)
-		const existingIconFile = iconDir.find((file) =>
+		const existingIconFile = existingIconFiles.find((file) =>
 			file.startsWith(path.basename(iconPath)),
 		);
 		if (existingIconFile) {
-			return path.join(path.dirname(iconPath), existingIconFile);
+			return iconDir.replace(/^public/, "") + "/" + existingIconFile;
 		}
 
 		// <link rel="manifest" href="/manifest.json">
@@ -132,10 +138,13 @@ function fetchPageIcon(src: URL, srcHast: Root): Promise<string> {
 		return "/" + iconPath + iconExt;
 	})()
 		// if an error is thrown, or response is null, use the default page icon
-		.catch(() => null)
+		.catch((e) => {
+			console.error("[rehypeIFrameClickToRun]", e);
+			return null;
+		})
 		.then((p) => p || defaultPageIcon);
 
-	pageIconMap.set(src.hostname, promise);
+	pageIconCache.set(src.hostname, promise);
 	return promise;
 }
 
@@ -206,6 +215,7 @@ export const rehypeUnicornIFrameClickToRun: Plugin<
 					src: String(src),
 					pageTitle: String(dataFrameTitle ?? "") || info.title || "",
 					pageIcon: info.iconFile,
+					pageIconFallback: defaultPageIcon,
 					propsToPreserve: JSON.stringify(propsToPreserve),
 				});
 

Diff for: public/icons/website.svg

@@ -7,14 +7,14 @@
 	max-width: var(--max-width_xl);
 	margin: 0 auto;
 
-	&:where(:not([data-hide-left-sidebar])) {
+	&:where(:not([data-hide-left-sidebar="true"])) {
 		@include from($tabletLarge) {
 			grid-template-columns: 25% 1fr;
 		}
 	}
 
 	// in tablet view, when the sidebar is hidden, the "content" column needs to be centered
-	&[data-hide-left-sidebar] {
+	&[data-hide-left-sidebar="true"] {
 		@include until($desktopSmall) {
 			max-width: var(--max-width_m);
 		}

Diff for: public/link.png

@@ -101,7 +101,7 @@ const showMoreText = translate(
 >
 	const showMore = document.querySelector("#toggleAllButton");
 	const showHideChapters = Array.from(
-		document.querySelectorAll("[data-dont-show-initially]"),
+		document.querySelectorAll("[data-dont-show-initially='true']"),
 	);
 
 	let expanded = false;