Introduce peer.paste

docs/plugins/peer.paste.md

@@ -0,0 +1,59 @@
+# Peer Paste Plugin
+
+`peer.paste` provides temporary, replicated text snippets for the P2NS network.
+
+## Overview
+
+- Store paste metadata/content in HyperDB.
+- Share via link (`/p/:id`) or API (`/api/pastes/:id/raw`).
+- Supports expiration, burn-after-read, and max-read limits.
+- Includes a lightweight web UI for create/list flows.
+
+## Routes
+
+- `POST /api/pastes` create a new paste
+- `GET /api/pastes` list active pastes
+- `GET /api/pastes/mine` list active pastes owned by local peer
+- `GET /api/pastes/:id` get paste metadata
+- `GET /api/pastes/:id/raw` consume/read paste content
+- `PUT /api/pastes/:id` update paste (owner only; authenticated)
+- `DELETE /api/pastes/:id` delete paste (owner only; authenticated)
+- `GET /api/stats` get aggregate service stats
+- `GET /api/health` lightweight plugin/db health check
+- `POST /api/admin/cleanup` run cleanup immediately (authenticated)
+- `GET /api/docs` interactive API documentation
+- `GET /api/openapi.json` OpenAPI 3 JSON specification
+- `GET /p/:id` human-readable paste page
+
+## HyperDB Schema
+
+Collection: `@peerpaste/pastes`
+
+Fields:
+- `id` (string, key)
+- `title` (string)
+- `content` (string)
+- `language` (string)
+- `ownerPeerId` (string)
+- `destroyOnRead` (bool)
+- `maxReads` (uint)
+- `readCount` (uint)
+- `createdAt` (uint)
+- `expiresAt` (uint)
+
+Index:
+- `pastes-by-expiry` on `expiresAt`
+
+## Lifecycle
+
+- `onInit()` ensures DB readiness and starts hourly cleanup.
+- Cleanup removes expired/consumed pastes and flushes DB.
+- `onShutdown()` clears cleanup interval.
+
+## Notes
+
+- Content currently replicates via HyperDB, so use reasonable paste size limits.
+- `POST` and `PUT` validate content and enforce a max length.
+- Raw consumption increments read count and can auto-delete on read constraints.
+- The `/api/docs` endpoint provides copy/paste-ready endpoint summaries.
+- The `/api/openapi.json` endpoint can be imported by API tooling.