docs: 📝 Write article about Versia 0.5

This commit is contained in:
Jesse Wierzbinski 2025-01-17 17:27:22 +01:00
parent d97efab9f3
commit 7589afd7b7
No known key found for this signature in database
16 changed files with 291 additions and 50 deletions

BIN
bun.lockb

Binary file not shown.

View file

@ -1,7 +1,4 @@
<template>
<!-- <article
class="$style.content mx-auto max-w-3xl prose prose-invert mt-10 prose-code:before:content-none prose-code:after:content-none prose-a:text-orange-500 prose-a:underline"
v-html="body"></article> -->
<article :class="[$style.content, 'prose prose-invert prose-code:before:content-none prose-code:after:content-none']" v-html="body"></article>
</template>
@ -29,8 +26,12 @@ defineProps<{
@apply h-6 w-6 flex-none rounded-full bg-gray-800;
}
.content :global :has(.header-anchor):hover .header-anchor {
@apply opacity-100;
}
.content :global .header-anchor {
@apply no-underline absolute w-16 md:w-auto text-right left-[calc(100%-3.75rem)] md:-left-10 text-gray-200
@apply no-underline absolute size-6 md:w-auto text-right opacity-0 duration-75 left-[calc(100%-3.75rem)] md:-left-10 text-gray-200
}
.content :global .header-anchor::before {

View file

@ -1,6 +1,9 @@
<template>
<nuxt-img :src="image" :width="width" :height="height" format="webp" alt="" :preload="true"
class="drop-shadow-2xl w-full rounded bg-zinc-900 ring-1 ring-white/10" />
<figure class="space-y-3 w-full">
<nuxt-img :src="image" :width="width" :height="height" format="webp" alt="" :preload="true"
class="drop-shadow-2xl w-full rounded bg-zinc-900 ring-1 ring-white/10" />
<figcaption v-if="caption" class="text-center text-sm text-gray-400">{{ caption }}</figcaption>
</figure>
</template>
<script lang="ts" setup>
@ -8,5 +11,6 @@ defineProps<{
image: string;
width?: number;
height?: number;
caption?: string;
}>();
</script>

View file

@ -1,6 +1,6 @@
<template>
<div class="mx-auto max-w-2xl text-center flex items-center justify-center gap-8 flex-col">
<h1 v-if="title" class="text-4xl font-bold tracking-tight text-gray-50 sm:text-5xl">
<h1 v-if="title" class="text-4xl font-bold tracking-tight text-gray-50 sm:text-5xl font-title">
{{ title }}
</h1>
<div>
@ -18,7 +18,7 @@ defineProps<{
}>();
const formatDate = (date?: string) => {
return new Intl.DateTimeFormat(undefined, {
return new Intl.DateTimeFormat("en-GB", {
year: "numeric",
month: "long",
day: "numeric",

View file

@ -0,0 +1,40 @@
<template>
<header class="shadow bg-zinc-800">
<div class="mx-auto max-w-7xl px-2 sm:px-4 lg:px-8">
<div class="relative flex h-16 justify-between">
<div class="relative z-10 flex px-2 lg:px-0">
<div class="flex flex-shrink-0 items-center">
<img class="h-8 w-auto" src="https://cdn.versia.pub/branding/icon.svg"
alt="Pink rounded square with three white star icons in the center" />
</div>
</div>
<div class="relative z-0 flex flex-1 items-center justify-center px-2">
<div class="w-full max-w-xl">
<label for="search" class="sr-only">Search</label>
<div class="relative">
<div class="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
<Icon name="tabler:search" class="size-5 text-gray-300" aria-hidden="true" />
</div>
<input id="search" name="search"
class="block w-full rounded-md border-0 bg-zinc-700 py-1.5 pl-10 pr-3 text-gray-200 ring-1 ring-inset ring-gray-700 placeholder:text-gray-300 focus:ring-2 focus:ring-inset focus:ring-pink-600 sm:text-sm sm:leading-6"
placeholder="Search" type="search" />
</div>
</div>
</div>
</div>
<nav class="hidden sm:flex sm:flex-row flex-col justify-evenly gap-x-8 gap-y-2 py-2" aria-label="Global">
<a v-for="item in navigation" :key="item.name" :href="item.href"
:class="['text-gray-100 hover:bg-zinc-700 hover:text-gray-50 inline-flex items-center justify-center rounded py-2 px-3 text-sm font-medium duration-200 w-full']">{{ item.name }}</a>
</nav>
</div>
</header>
</template>
<script lang="ts" setup>
const navigation = [
{ name: "Dashboard", href: "#", current: true },
{ name: "Team", href: "#", current: false },
{ name: "Projects", href: "#", current: false },
{ name: "Calendar", href: "#", current: false },
];
</script>

View file

@ -46,6 +46,7 @@ export const getPost = async (path: string): Promise<Post | null> => {
height: header.image_height
? Number(header.image_height)
: undefined,
credit: header.image_credit,
},
title: header.title,
path,

View file

@ -0,0 +1,199 @@
---
title: Versia 0.5 is here!
created_at: 1737126070000
description: The latest and greatest version of Versia is here! This release is all about small changes and tweaks to make exchanges more consistent.
image: /images/vibrant-abstract-purple-pink.jpg
image_credit: Steve Johnson, Pexels
image_width: 1280
image_height: 720
author: CPlusPatch
author_image: https://cpluspatch.com/images/avatars/jessew.png
author_handle: @jessew
---
Today, on January 17th 2025, I [merged](https://github.com/versia-pub/docs/pull/35) Versia 0.5 into the docs' `main` branch.
This release doesn't bring any major changes, being mostly renames and tweaks to make data exchanges more consistent. The most notable changes are:
- Signature headers have been renamed
- The nonce in signatures has been replaced by a timestamp
- Groups are better documented
- (and moved to an extension :p)
- [Versia Links](https://versia.pub/links) are a new feature
- Some [`Collections`](https://versia.pub/structures/collection) have been swapped for the simpler [`URICollection`](https://versia.pub/structures/collection#uri-collection) format
- A bunch of new extensions
You can find the full changelog [here](https://versia.pub/changelog).
Let's go over everything in more detail.
## Line endings
For the sake of consistency across OSes and editors, all text fields in Versia now use Unix line endings (`\n`). Most servers already use Unix line endings, but it's good to be explicit about it.
## Renamed headers
The following headers have been renamed:
- `X-Signature` --> `Versia-Signature`
- `X-Signed-By` --> `Versia-Signed-By`
Why? Well, [RFC 6648](https://tools.ietf.org/html/rfc6648) happened (tldr: the `X-` prefix is deprecated).
## Nonce no more
The `X-Nonce` header in signatures has been replaced by a timestamp. Replay attacks are not really a big concern in the Versia security model, but verifying signature freshness is still a good idea.
### What does this prevent?
Here's an example: Alice accidentally posts her full social security number to a public Versia server. Obviously, she immediately deletes the post, but someone with a malicious instance could replay the note federation request to other servers, essentially bringing it back from the dead.
This is a very contrived example, but it's a good illustration of why we should verify the freshness of signatures.
## Rate limiting
Obeying IETF draft [polli-ratelimit-headers-02](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html) is now mandatory for all Versia implementations. Implementations running on weaker hardware can sometimes struggle with the load of a large number of requests, so it's important to have a way to throttle federation!
As to the draft itself, it was chosen for its simplicity, so you shouldn't have too much trouble implementing it.
## Groups
Turns out, [`Groups`](https://versia.pub/extensions/groups) were missing a lot of significant information, like how to actually subscribe and receive updates from them. This has been fixed.
The new system introduces a very similar system to the one used for [`Follows`](https://versia.pub/entities/follow), with the following new entities:
- `pub.versia:groups/Subscribe`
- `pub.versia:groups/Unsubscribe`
- `pub.versia:groups/SubscribeAccept`
- `pub.versia:groups/SubscribeReject`
As to federation, the [`Groups`](https://versia.pub/extensions/groups)'s home instance can now federate all notes posted to it while keeping the original author's signature, using the new `pub.versia:groups/Federate` entity. This avoids the need for forwardable signatures, which are a pain to implement.
To top that all off, `Groups` have [been moved to an extension](https://versia.pub/extensions/groups), because they were getting too big for the main spec.
## Versia Links
A common problem on ActivityPub is that you can easily link to a user or a note via its URI, but to interact with it, you need to have your implementation look up that URI in your favourite client. This is a pain. There should be a way to automatically open your favorite client when you click on a link, right?
Well, the issue comes from the fact that there's no way for a client to tell which URIs are Versia URIs (e.g., `https://versia.social/users/jessew`) and which are not (like `https://google.com`). This is where Versia Links come in.
They look like this:
```plaintext
# Opens a user profile
web+versia://users/bob.social/alice
# Opens a note
web+versia://notes/jimbob.com/01902e09-0f8b-72de-8ee3-9afc0cf5eae1
# Opens the composer with a reply to a note
web+versia://reply/bob.social/01902e09-0f8b-72de-8ee3-9afc0cf5eae1
```
The `web+` prefix allows Web clients to register support for the `web+versia` scheme, which will open the link in the user's Versia client. This is a simple way to make Versia URIs stand out from the rest.
Versia Links are meant to be used in instances' web UIs, for logged-out users. This replaces the "type your instance's domain" popup that was previously used in [Mastodon](https://joinmastodon.org/), for example.
For more information, check out the [Versia Links spec](https://versia.pub/links).
## Timestamp change
All timestamps now use [RFC 3339](https://tools.ietf.org/html/rfc3339) instead of ISO 8601. [RFC 3339](https://tools.ietf.org/html/rfc3339) can be thought as a more restricted version of ISO 8601, which means that most implementations should already be compatible with it.
```plaintext
# ISO 8601
2025-01-17T12:00:00Z
# RFC 3339
2025-01-17T12:00:00Z
# They're the same!
# Except now you can't do this horrible thing anymore:
2025-W03-5T17:04:29/PT2M
```
[Here's a helpful visualization of the differences between the two](https://ijmacd.github.io/rfc3339-iso8601/).
### Unix timestamps?
Unix timestamps are great for machines, but they're not very human-readable. [RFC 3339](https://tools.ietf.org/html/rfc3339) is a good compromise between the two, being both human-readable and easily machine-readable.
## `$schema` in Entities
Entities can now optionally have a `$schema` field, which allows implementations to include a [JSON Schema](https://json-schema.org/) inside the entity.
This is meant for human use only, and not for either clients or servers to validate the entity. Including the implementation's JSON schema in the entity itself can be useful for debugging and documentation purposes.
## URICollection
Some `Collections` have been swapped for the simpler `URICollection` format. This is a simple list of URIs, which can be used for things like a list of followers, for example.
It is much easier to implement than the full `Collection` format, plus it's also more lightweight.
```json
{
"author": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771",
"first": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=1",
"last": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=3",
"total": 46,
"next": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=2",
"previous": null,
"items": [
"https://versia.social/users/f8b0d4b4-d354-4798-bbc5-c2ba8acabfe3",
"https://social.bob.com/u/2B27E62snga763"
]
}
```
## Note collections
[Notes](https://versia.pub/entities/note) now have a `collections` field, which regroups `outbox`, `likes`, `replies`, etc.
```json
{
// ...
"collections": {
"replies": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/replies",
"quotes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/quotes",
"pub.versia:likes/Likes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/likes",
"pub.versia:likes/Dislikes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/dislikes",
"pub.versia:reactions/Reactions": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/reactions"
}
}
```
This is a simpler structure than in Versia 0.4, where everything was its own top-level field:
```json
{
// ...
"replies": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/replies",
"quotes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/quotes",
"extensions": {
"pub.versia:likes": {
"likes": "https://versia.social/objects/01902e09-0f8b-72de-8ee3-9afc0cf5eae1/likes",
}
}
}
```
## Interaction Controls
The new [Interaction Controls Extension](https://versia.pub/extensions/interaction-controls) allows users to control who can interact with their posts, just like on Bluesky or Twitter. This is great when you're often the target of spam or harassment.
The system has a lot of flexibility while still being simple enough to implement in a weekend or two.
## Smaller stuff
- Usernames can now have uppercase characters. Also, they're now case-insensitive, so `jessew` and `JesseW` are the same user.
- The [Vanity Extension](https://versia.pub/extensions/vanity) now supports a `timezone` field.
- Docs have been improved across the board, with [more examples](https://versia.pub/federation/example) and explanations.
- [`Reports`](https://versia.pub/extensions/reports) are now transient, and the `reason` field was replaced by a `tags` field.
## Conclusion
Is this a large breaking change that will require a lot of work to implement? No, not really. Is it better than the previous version? Yes, definitely.
I hope you have a good time implementing this release. If you have any questions, feel free to contact me, Jesse, [on these socials](https://cpluspatch.com/contact). I'm always glad to help.
Happy hacking!

View file

@ -1,32 +0,0 @@
---
title: A test post for the Versia Blog
created_at: 1700020246000
description: This is a test post for the Versia Blog. I write this post to test the blog system.
image: https://images.pexels.com/photos/2646237/pexels-photo-2646237.jpeg
image_width: 6000
image_height: 4000
author: CPlusPatch
author_image: https://mk-cdn.cpluspatch.com/uploads/5cd850d3-6b6b-4543-97ca-9854b9dbf9f3.webp
author_handle: @jessewh
---
Lorem ipsum odor amet, consectetuer adipiscing elit. Habitasse augue eu phasellus volutpat aliquam venenatis dui. Fusce vitae vivamus per lectus, semper tristique. Lacus semper nam natoque cras gravida facilisis accumsan vivamus. Cras euismod non taciti ligula aptent cras. Mauris adipiscing curae mauris aliquet mi venenatis tempor. Quis congue sollicitudin ullamcorper purus non netus nascetur. Ipsum congue scelerisque tristique lobortis amet.
# I love headers
![Image](https://images.pexels.com/photos/2646237/pexels-photo-2646237.jpeg)
Faucibus habitant non tortor maximus bibendum suscipit accumsan scelerisque felis. Mattis aliquet sociosqu montes pretium fusce cras nibh. Diam morbi habitant vulputate morbi; risus suscipit. Vulputate facilisis quam primis penatibus vel elementum dolor tempor. Posuere dictumst est tempus purus rutrum risus faucibus faucibus. Sem per donec nisl sociosqu inceptos eu velit. Non aenean sagittis lacus vivamus donec ac. Ipsum morbi luctus parturient, dignissim justo massa ipsum. Metus augue nascetur ornare mattis sagittis nec blandit vitae. Semper vivamus accumsan suspendisse risus senectus molestie. `moe lester`.
```python
def hello():
print("Hello, World!")
```
## Me too
Eleifend platea conubia turpis enim iaculis nisi. Habitant congue proin elementum sed ultrices turpis aptent. Sem arcu magnis sollicitudin convallis ullamcorper vitae. Aporta dignissim praesent vitae efficitur habitant. Gravida tincidunt quam facilisis, pulvinar ante et conubia. Sapien quisque ex tortor bibendum ut feugiat felis faucibus ornare. Magna auctor platea vel non massa laoreet venenatis dis auctor. Iaculis mus tempor hendrerit ullamcorper fringilla odio donec ex. Amet rutrum magna efficitur a ad per accumsan.
Vulputate est bibendum lobortis cubilia quisque habitasse. Ante suspendisse libero consequat quis suspendisse aenean. Eget pharetra turpis arcu varius sapien? Cras vel tempus fermentum volutpat ad fusce mauris. Dignissim ad ligula lacinia cursus sodales. Condimentum erat mattis arcu mus velit vitae fames. Mollis faucibus consectetur varius in finibus duis sollicitudin aliquam torquent. Venenatis imperdiet mollis velit maximus duis enim habitant.
Faucibus tempus massa senectus malesuada vestibulum tristique. Platea nibh erat euismod libero, felis luctus egestas. Dis iaculis nascetur platea dis urna varius tempor condimentum lacinia. Ullamcorper tempus ad et proin tortor. Odio odio lobortis ac posuere maecenas nibh tempus dis. Ipsum pretium senectus pretium eu vulputate. Taciti viverra rhoncus ipsum egestas natoque praesent. Congue interdum scelerisque consequat, ornare penatibus tincidunt litora.

View file

@ -1,11 +1,8 @@
<script setup lang="ts">
</script>
<template>
<main :class="[$style.content, 'w-full h-full min-h-screen bg-gradient-to-tr from-zinc-900 to-zinc-800']">
<main :class="['size-full min-h-screen bg-zinc-900 font-sans']">
<slot />
</main>
</template>
<style lang="css" module>
.content {
font-family: Inter, sans-serif;
}
</style>
</template>

View file

@ -94,6 +94,23 @@ export default defineNuxtConfig({
future: {
compatibilityVersion: 4,
},
fonts: {
defaults: {
subsets: ["latin", "latin-ext"],
},
},
security: {
headers: {
contentSecurityPolicy: {
"img-src": [
"'self'",
"data:",
"images.pexels.com",
"cdn.versia.pub",
],
},
},
},
image: {
domains: ["images.pexels.com"],
},

View file

@ -49,12 +49,14 @@
"markdown-it-toc-done-right": "^4.2.0",
"nuxt": "^3.13.2",
"nuxt-security": "^2.0.0",
"sharp": "^0.33.5",
"shiki": "^1.22.2",
"vue": "^3.5.12",
"vue-router": "^4.4.5"
},
"devDependencies": {
"@biomejs/biome": "^1.9.4",
"@iconify-json/tabler": "^1.2.6",
"@types/bun": "^1.1.12",
"@types/markdown-it-container": "^2.0.10",
"tailwindcss": "^3.4.14"

View file

@ -1,7 +1,7 @@
<template>
<div v-if="post" class="mx-auto max-w-3xl py-24 sm:py-32 px-6 lg:px-8 flex flex-col items-center gap-10">
<Title v-if="post.title" :created_at="post.created_at" :title="post.title" />
<Image v-if="post.image" :image="post.image.url" :width="post.image.width" :height="post.image.height" />
<Image v-if="post.image" :image="post.image.url" :width="post.image.width" :height="post.image.height" :caption="post.image.credit" />
<Content :body="body" />
</div>
</template>

View file

@ -1,7 +1,9 @@
<template>
<NuxtLink href="/articles/test/test-file" class="text-gray-200 underline">nyaa</NuxtLink>
<span></span>
</template>
<script lang="ts" setup>
import { navigateTo } from "#imports";
navigateTo("/articles/2025/01/17/versia-05");
</script>

Binary file not shown.

After

Width:  |  Height:  |  Size: 133 KiB

View file

@ -5,5 +5,13 @@ import type { Config } from "tailwindcss";
// Default are on https://tailwindcss.nuxtjs.org/tailwind/config#default-configuration
export default (<Partial<Config>>{
plugins: [forms, typography],
theme: {
extend: {
fontFamily: {
title: ["Poppins", "sans-serif"],
sans: ["Inter", "sans-serif"],
},
},
},
content: [],
});

View file

@ -2,6 +2,7 @@ export interface FrontMatter {
title: string;
description: string;
image: string;
image_credit?: string;
image_width?: number;
image_height?: number;
created_at: string;
@ -16,6 +17,7 @@ export interface Post {
description: string;
image: {
url: string;
credit?: string;
width?: number;
height?: number;
};