Skip to content

Commit 3d93bce

Browse files
melvincarvalhomelvincarvalho
committed
docs: add missing feature documentation
New docs: - docs/nostr.md — relay, NIP support, client usage - docs/notifications.md — WebSocket solid-0.1 protocol, live reload - docs/quotas.md — storage limits, CLI management - docs/invites.md — invite-only registration - docs/mashlib.md — data browser modes, SolidOS UI, profile pages Also: - Update README docs table with all 15 docs - Fix duplicate quotas section in configuration.md Fixes JavaScriptSolidServer#218
1 parent 15efda1 commit 3d93bce

7 files changed

Lines changed: 250 additions & 39 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,13 +91,18 @@ Full options: [docs/configuration.md](docs/configuration.md)
9191
|-------|------|
9292
| Configuration & Options | [docs/configuration.md](docs/configuration.md) |
9393
| Authentication | [docs/authentication.md](docs/authentication.md) |
94+
| Mashlib / SolidOS UI | [docs/mashlib.md](docs/mashlib.md) |
95+
| WebSocket Notifications | [docs/notifications.md](docs/notifications.md) |
9496
| Git Support | [docs/git-support.md](docs/git-support.md) |
97+
| Nostr Relay | [docs/nostr.md](docs/nostr.md) |
9598
| ActivityPub & Mastodon API | [docs/activitypub.md](docs/activitypub.md) |
9699
| remoteStorage | [docs/remotestorage.md](docs/remotestorage.md) |
97-
| Security & Subdomain Mode | [docs/security.md](docs/security.md) |
98-
| HTTP 402 Payments | [docs/payments.md](docs/payments.md) |
99100
| WebRTC & Tunnel | [docs/webrtc.md](docs/webrtc.md) |
100101
| MongoDB `/db/` Route | [docs/mongodb.md](docs/mongodb.md) |
102+
| HTTP 402 Payments | [docs/payments.md](docs/payments.md) |
103+
| Storage Quotas | [docs/quotas.md](docs/quotas.md) |
104+
| Invite-Only Registration | [docs/invites.md](docs/invites.md) |
105+
| Security & Subdomain Mode | [docs/security.md](docs/security.md) |
101106
| Architecture & Structure | [docs/architecture.md](docs/architecture.md) |
102107

103108
## Comparison

‎docs/configuration.md‎

Lines changed: 0 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -355,43 +355,6 @@ jss quota reconcile alice
355355

356356
Supported formats: `50MB`, `1GB`, `500KB`, `1TB`
357357

358-
## Storage Quotas
359-
360-
Limit storage per pod to prevent abuse and manage resources:
361-
362-
```bash
363-
jss start --default-quota 50MB
364-
```
365-
366-
### Managing Quotas
367-
368-
```bash
369-
# Set quota for a user (overrides default)
370-
jss quota set alice 100MB
371-
372-
# Show quota info
373-
jss quota show alice
374-
# alice:
375-
# Used: 12.5 MB
376-
# Limit: 100 MB
377-
# Free: 87.5 MB
378-
# Usage: 12%
379-
380-
# Recalculate from actual disk usage
381-
jss quota reconcile alice
382-
```
383-
384-
### How It Works
385-
386-
- Quotas are tracked incrementally on PUT, POST, and DELETE operations
387-
- When quota is exceeded, the server returns HTTP 507 Insufficient Storage
388-
- Each pod stores its quota in `/{pod}/.quota.json`
389-
- Use `reconcile` to fix quota drift from manual file changes
390-
391-
### Size Formats
392-
393-
Supported formats: `50MB`, `1GB`, `500KB`, `1TB`
394-
395358
### Mashlib Data Browser
396359

397360
Enable the [SolidOS Mashlib](https://github.com/SolidOS/mashlib) data browser for RDF resources. Two modes are available:

‎docs/invites.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Invite-Only Registration
2+
3+
Control who can create accounts by requiring invite codes.
4+
5+
```bash
6+
jss start --idp --invite-only
7+
```
8+
9+
## Managing Invite Codes
10+
11+
```bash
12+
# Create a single-use invite
13+
jss invite create
14+
# Created invite code: ABCD1234
15+
16+
# Create multi-use invite with note
17+
jss invite create -u 5 -n "For team members"
18+
19+
# List all active invites
20+
jss invite list
21+
# CODE USES CREATED NOTE
22+
# -------------------------------------------------------
23+
# ABCD1234 0/1 2026-01-03
24+
# EFGH5678 2/5 2026-01-03 For team members
25+
26+
# Revoke an invite
27+
jss invite revoke ABCD1234
28+
```
29+
30+
## How It Works
31+
32+
| Mode | Registration | Pod Creation |
33+
|------|--------------|--------------|
34+
| Open (default) | Anyone can register | Anyone can create pods |
35+
| Invite-only | Requires valid invite code | Via registration only |
36+
37+
When `--invite-only` is enabled:
38+
- The registration page shows an "Invite Code" field
39+
- Invalid or expired codes are rejected with an error
40+
- Each use decrements the invite's remaining uses
41+
- Depleted invites are automatically removed
42+
43+
Invite codes are stored in `.server/invites.json` in your data directory.

‎docs/mashlib.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Mashlib Data Browser
2+
3+
Enable the [SolidOS Mashlib](https://github.com/SolidOS/mashlib) data browser for RDF resources.
4+
5+
## Modes
6+
7+
**CDN Mode** (recommended for getting started):
8+
```bash
9+
jss start --mashlib-cdn --conneg
10+
```
11+
Loads mashlib from unpkg.com CDN. Zero footprint — no local files needed.
12+
13+
**Local Mode** (for production/offline):
14+
```bash
15+
jss start --mashlib --conneg
16+
```
17+
Serves mashlib from `src/mashlib-local/dist/`. Requires building mashlib locally:
18+
```bash
19+
cd src/mashlib-local
20+
npm install && npm run build
21+
```
22+
23+
**ES Module Mode** (for custom or next-gen mashlib builds):
24+
```bash
25+
jss start --mashlib-module https://example.com/mashlib.js
26+
```
27+
Loads an ES module-based data browser from any URL. Uses `<script type="module">` and `<div id="mashlib">` (self-initializing). CSS is auto-derived by replacing `.js` with `.css`. Content negotiation is auto-enabled.
28+
29+
## How It Works
30+
31+
1. Browser requests `/alice/public/data.ttl` with `Accept: text/html`
32+
2. Server returns Mashlib HTML wrapper
33+
3. Mashlib fetches the actual data via content negotiation
34+
4. Mashlib renders an interactive, editable view
35+
36+
**Note:** Mashlib works best with `--conneg` enabled for Turtle support.
37+
38+
## Modern UI (SolidOS UI)
39+
40+
```bash
41+
jss start --mashlib --solidos-ui --conneg
42+
```
43+
44+
Serves a modern Nextcloud-style UI shell while reusing mashlib's data layer:
45+
- Modern file browser with breadcrumb navigation
46+
- Profile, Contacts, Sharing, and Settings views
47+
- Path-based URLs (browser URL reflects current resource)
48+
- Responsive design for mobile devices
49+
50+
Requires solidos-ui dist files in `src/mashlib-local/dist/solidos-ui/`. See [solidos-ui](https://github.com/solidos/solidos/tree/main/workspaces/solidos-ui) for details.
51+
52+
## Profile Pages
53+
54+
Pod profiles (`/alice/`) use HTML with embedded JSON-LD data islands and are rendered using:
55+
- [mashlib-jss](https://github.com/JavaScriptSolidServer/mashlib-jss) — A fork of mashlib with `getPod()` fix for path-based pods
56+
- [solidos-lite](https://github.com/SolidOS/solidos-lite) — Parses JSON-LD data islands into the RDF store
57+
58+
This allows profiles to work without server-side content negotiation while still providing full SolidOS editing capabilities.

‎docs/nostr.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Nostr Relay
2+
3+
Integrated NIP-01/NIP-11/NIP-16 Nostr relay running on the same port as the Solid server.
4+
5+
```bash
6+
jss start --nostr
7+
```
8+
9+
## Endpoint
10+
11+
`wss://your.pod/relay` (configurable via `--nostr-path`)
12+
13+
## Supported NIPs
14+
15+
- **NIP-01** — Basic protocol flow (EVENT, REQ, CLOSE)
16+
- **NIP-11** — Relay information document (`GET /relay` with `Accept: application/nostr+json`)
17+
- **NIP-16** — Event treatment (regular, replaceable, ephemeral)
18+
19+
## Options
20+
21+
| Option | Description | Default |
22+
|--------|-------------|---------|
23+
| `--nostr` | Enable Nostr relay | false |
24+
| `--nostr-path <path>` | WebSocket path | /relay |
25+
| `--nostr-max-events <n>` | Max events in memory | 1000 |
26+
27+
## How It Works
28+
29+
- Events are stored in memory (up to `--nostr-max-events`)
30+
- Replaceable events (kinds 0, 3, 10000-19999) replace previous events by the same pubkey
31+
- Ephemeral events (kinds 20000-29999) are broadcast but not stored
32+
- Parameterized replaceable events (kinds 30000-39999) use the `d` tag for deduplication
33+
- Rate limiting: 60 events per socket per minute
34+
35+
## Client Usage
36+
37+
```javascript
38+
import { Relay } from 'nostr-tools';
39+
40+
const relay = await Relay.connect('wss://your.pod/relay');
41+
42+
// Subscribe
43+
const sub = relay.subscribe([{ kinds: [1], limit: 10 }], {
44+
onevent(event) { console.log(event); }
45+
});
46+
47+
// Publish
48+
await relay.publish(signedEvent);
49+
```
50+
51+
## Nostr Authentication (NIP-98)
52+
53+
JSS also supports NIP-98 HTTP Auth for Solid operations. See [docs/authentication.md](authentication.md) for details on:
54+
- NIP-98 Schnorr signature authentication
55+
- `did:nostr` → WebID resolution
56+
- Linking Nostr identity to your WebID profile

‎docs/notifications.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# WebSocket Notifications
2+
3+
Real-time notifications for resource changes using the solid-0.1 protocol (SolidOS compatible).
4+
5+
```bash
6+
jss start --notifications
7+
```
8+
9+
## Discovery
10+
11+
Clients discover the WebSocket URL via the `Updates-Via` header:
12+
13+
```bash
14+
curl -I http://localhost:3000/alice/public/
15+
# Updates-Via: ws://localhost:3000/.notifications
16+
```
17+
18+
## Protocol
19+
20+
```
21+
Server: protocol solid-0.1
22+
Client: sub http://localhost:3000/alice/public/data.json
23+
Server: ack http://localhost:3000/alice/public/data.json
24+
Server: pub http://localhost:3000/alice/public/data.json (on change)
25+
```
26+
27+
## How It Works
28+
29+
1. Client connects to the WebSocket URL from `Updates-Via`
30+
2. Server sends `protocol solid-0.1` greeting
31+
3. Client subscribes: `sub <resource-url>`
32+
4. Server acknowledges: `ack <resource-url>`
33+
5. On any change (PUT, PATCH, DELETE), server broadcasts: `pub <resource-url>`
34+
6. Container subscriptions also fire when child resources change
35+
36+
## ACL Enforcement
37+
38+
- Anonymous clients can subscribe to public resources
39+
- Private resource subscriptions require authentication
40+
- Cross-origin subscriptions are rejected
41+
42+
## Live Reload
43+
44+
For development, `--live-reload` injects a script that auto-refreshes the browser when files change on disk:
45+
46+
```bash
47+
jss start --live-reload --notifications
48+
```
49+
50+
File system changes (editing files directly) also trigger WebSocket notifications.

‎docs/quotas.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Storage Quotas
2+
3+
Limit storage per pod to prevent abuse and manage resources.
4+
5+
```bash
6+
jss start --default-quota 50MB
7+
```
8+
9+
## Managing Quotas
10+
11+
```bash
12+
# Set quota for a user (overrides default)
13+
jss quota set alice 100MB
14+
15+
# Show quota info
16+
jss quota show alice
17+
# alice:
18+
# Used: 12.5 MB
19+
# Limit: 100 MB
20+
# Free: 87.5 MB
21+
# Usage: 12%
22+
23+
# Recalculate from actual disk usage
24+
jss quota reconcile alice
25+
```
26+
27+
## How It Works
28+
29+
- Quotas are tracked incrementally on PUT, POST, and DELETE operations
30+
- When quota is exceeded, the server returns HTTP 507 Insufficient Storage
31+
- Each pod stores its quota in `/{pod}/.quota.json`
32+
- Use `reconcile` to fix quota drift from manual file changes
33+
34+
## Size Formats
35+
36+
Supported formats: `50MB`, `1GB`, `500KB`, `1TB`

0 commit comments

Comments
 (0)