docs: Sketch NIF-77 sync and ACLs
This commit is contained in:
@@ -1,70 +1,95 @@
|
||||
# Parrhesia Shared API + Local API Design (Option 1)
|
||||
# Parrhesia Shared API
|
||||
|
||||
## 1) Goal
|
||||
## 1. Goal
|
||||
|
||||
Expose a stable in-process API for embedding apps **and** refactor server transports to consume the same API.
|
||||
Expose a stable in-process API that:
|
||||
|
||||
Desired end state:
|
||||
- is used by WebSocket, HTTP management, local callers, and sync workers,
|
||||
- keeps protocol and storage behavior in one place,
|
||||
- stays neutral about application-level replication semantics.
|
||||
|
||||
- WebSocket server, HTTP management, and embedding app all call one shared core API.
|
||||
- Transport layers (WS/HTTP/local) only do framing, auth header extraction, and response encoding.
|
||||
- Policy/storage/fanout/business semantics live in one place.
|
||||
|
||||
This keeps everything in the same dependency (`:parrhesia`) and avoids a second package.
|
||||
This document defines the Parrhesia contract. It does **not** define Tribes or Ash sync behavior.
|
||||
|
||||
---
|
||||
|
||||
## 2) Key architectural decision
|
||||
## 2. Scope
|
||||
|
||||
Previous direction: `Parrhesia.Local.*` as primary public API.
|
||||
### In scope
|
||||
|
||||
Updated direction (this doc):
|
||||
- event ingest/query/count parity with WebSocket behavior,
|
||||
- local subscription APIs,
|
||||
- NIP-98 validation helpers,
|
||||
- management/admin helpers,
|
||||
- remote relay sync worker control and health reporting.
|
||||
|
||||
- Introduce **shared core API modules** under `Parrhesia.API.*`.
|
||||
- Make server code (`Parrhesia.Web.Connection`, management handlers) delegate to `Parrhesia.API.*`.
|
||||
- Keep `Parrhesia.Local.*` as optional convenience wrappers over `Parrhesia.API.*`.
|
||||
### Out of scope
|
||||
|
||||
This ensures no divergence between local embedding behavior and websocket behavior.
|
||||
- resource registration,
|
||||
- trusted app writers,
|
||||
- mutation payload semantics,
|
||||
- conflict resolution,
|
||||
- replay winner selection,
|
||||
- Ash action mapping.
|
||||
|
||||
Those belong in app profiles such as `TRIBES-NOSTRSYNC`, not in Parrhesia.
|
||||
|
||||
---
|
||||
|
||||
## 3) Layered design
|
||||
## 3. Layering
|
||||
|
||||
```text
|
||||
Transport layer
|
||||
- Parrhesia.Web.Connection (WS)
|
||||
- Parrhesia.Web.Management (HTTP)
|
||||
- Parrhesia.Local.* wrappers (in-process)
|
||||
Transport / embedding / background workers
|
||||
- Parrhesia.Web.Connection
|
||||
- Parrhesia.Web.Management
|
||||
- Parrhesia.Local.*
|
||||
- Parrhesia.Sync.*
|
||||
|
||||
Shared API layer
|
||||
Shared API
|
||||
- Parrhesia.API.Auth
|
||||
- Parrhesia.API.Events
|
||||
- Parrhesia.API.Stream (optional)
|
||||
- Parrhesia.API.Admin (optional, for management methods)
|
||||
- Parrhesia.API.Stream
|
||||
- Parrhesia.API.Admin
|
||||
- Parrhesia.API.Identity
|
||||
- Parrhesia.API.ACL
|
||||
- Parrhesia.API.Sync
|
||||
|
||||
Domain/runtime dependencies
|
||||
Runtime internals
|
||||
- Parrhesia.Policy.EventPolicy
|
||||
- Parrhesia.Storage.* adapters
|
||||
- Parrhesia.Storage.*
|
||||
- Parrhesia.Groups.Flow
|
||||
- Parrhesia.Subscriptions.Index
|
||||
- Parrhesia.Fanout.MultiNode
|
||||
- Parrhesia.Telemetry
|
||||
```
|
||||
|
||||
Rule: all ingest/query/count decisions happen in `Parrhesia.API.Events`.
|
||||
Rule: transport framing stays at the edge. Business decisions happen in `Parrhesia.API.*`.
|
||||
|
||||
---
|
||||
|
||||
## 4) Public module plan
|
||||
## 4. Core Context
|
||||
|
||||
## 4.1 `Parrhesia.API.Auth`
|
||||
```elixir
|
||||
defmodule Parrhesia.API.RequestContext do
|
||||
defstruct authenticated_pubkeys: MapSet.new(),
|
||||
actor: nil,
|
||||
caller: :local,
|
||||
metadata: %{}
|
||||
end
|
||||
```
|
||||
|
||||
`caller` is for telemetry and policy parity, for example `:websocket`, `:http`, `:local`, or `:sync`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Public Modules
|
||||
|
||||
### 5.1 `Parrhesia.API.Auth`
|
||||
|
||||
Purpose:
|
||||
- event validation helpers
|
||||
- NIP-98 verification
|
||||
- optional embedding account resolution hook
|
||||
|
||||
Proposed functions:
|
||||
- event validation helpers,
|
||||
- NIP-98 verification,
|
||||
- optional embedding account resolution.
|
||||
|
||||
```elixir
|
||||
@spec validate_event(map()) :: :ok | {:error, term()}
|
||||
@@ -77,100 +102,65 @@ Proposed functions:
|
||||
{:ok, Parrhesia.API.Auth.Context.t()} | {:error, term()}
|
||||
```
|
||||
|
||||
`validate_nip98/4` options:
|
||||
|
||||
```elixir
|
||||
account_resolver: (pubkey_hex :: String.t(), auth_event :: map() ->
|
||||
{:ok, account :: term()} | {:error, term()})
|
||||
```
|
||||
|
||||
Context struct:
|
||||
|
||||
```elixir
|
||||
defmodule Parrhesia.API.Auth.Context do
|
||||
@enforce_keys [:pubkey, :auth_event]
|
||||
defstruct [:pubkey, :auth_event, :account, claims: %{}]
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4.2 `Parrhesia.API.Events`
|
||||
### 5.2 `Parrhesia.API.Events`
|
||||
|
||||
Purpose:
|
||||
- canonical ingress/query/count API used by WS + local + HTTP integrations.
|
||||
|
||||
Proposed functions:
|
||||
- canonical ingest/query/count path used by WS, HTTP, local callers, and sync workers.
|
||||
|
||||
```elixir
|
||||
@spec publish(map(), keyword()) :: {:ok, Parrhesia.API.Events.PublishResult.t()} | {:error, term()}
|
||||
@spec query([map()], keyword()) :: {:ok, [map()]} | {:error, term()}
|
||||
@spec count([map()], keyword()) :: {:ok, non_neg_integer() | map()} | {:error, term()}
|
||||
@spec publish(map(), keyword()) ::
|
||||
{:ok, Parrhesia.API.Events.PublishResult.t()} | {:error, term()}
|
||||
|
||||
@spec query([map()], keyword()) ::
|
||||
{:ok, [map()]} | {:error, term()}
|
||||
|
||||
@spec count([map()], keyword()) ::
|
||||
{:ok, non_neg_integer() | map()} | {:error, term()}
|
||||
```
|
||||
|
||||
Request context:
|
||||
Required options:
|
||||
|
||||
```elixir
|
||||
defmodule Parrhesia.API.RequestContext do
|
||||
defstruct authenticated_pubkeys: MapSet.new(),
|
||||
actor: nil,
|
||||
metadata: %{}
|
||||
end
|
||||
```
|
||||
- `:context` - `%Parrhesia.API.RequestContext{}`
|
||||
|
||||
Publish result:
|
||||
`publish/2` must preserve current `EVENT` semantics:
|
||||
|
||||
```elixir
|
||||
defmodule Parrhesia.API.Events.PublishResult do
|
||||
@enforce_keys [:event_id, :accepted, :message]
|
||||
defstruct [:event_id, :accepted, :message]
|
||||
end
|
||||
```
|
||||
1. size checks,
|
||||
2. `Protocol.validate_event/1`,
|
||||
3. `EventPolicy.authorize_write/2`,
|
||||
4. group handling,
|
||||
5. persistence or control-event path,
|
||||
6. local plus multi-node fanout,
|
||||
7. telemetry.
|
||||
|
||||
### Publish semantics (must match websocket EVENT)
|
||||
|
||||
Pipeline in `publish/2`:
|
||||
|
||||
1. frame/event size limits
|
||||
2. `Parrhesia.Protocol.validate_event/1`
|
||||
3. `Parrhesia.Policy.EventPolicy.authorize_write/2`
|
||||
4. group handling (`Parrhesia.Groups.Flow.handle_event/1`)
|
||||
5. persistence path (`put_event`, deletion, vanish, ephemeral rules)
|
||||
6. fanout (local + multi-node)
|
||||
7. telemetry emit
|
||||
|
||||
Return shape mirrors Nostr `OK` semantics:
|
||||
Return shape mirrors `OK`:
|
||||
|
||||
```elixir
|
||||
{:ok, %PublishResult{event_id: id, accepted: true, message: "ok: event stored"}}
|
||||
{:ok, %PublishResult{event_id: id, accepted: false, message: "blocked: ..."}}
|
||||
```
|
||||
|
||||
### Query/count semantics (must match websocket REQ/COUNT)
|
||||
`query/2` and `count/2` must preserve current `REQ` and `COUNT` behavior, including giftwrap restrictions and server-side filter validation.
|
||||
|
||||
`query/2` and `count/2`:
|
||||
|
||||
1. validate filters
|
||||
2. run read policy (`EventPolicy.authorize_read/2`)
|
||||
3. call storage with `requester_pubkeys` from context
|
||||
4. return ordered events/count payload
|
||||
|
||||
Giftwrap restrictions (`kind 1059`) must remain identical to websocket behavior.
|
||||
|
||||
---
|
||||
|
||||
## 4.3 `Parrhesia.API.Stream` (optional but recommended)
|
||||
### 5.3 `Parrhesia.API.Stream`
|
||||
|
||||
Purpose:
|
||||
- local in-process subscriptions using same subscription index/fanout model.
|
||||
|
||||
Proposed functions:
|
||||
- in-process subscription surface with the same semantics as a WebSocket `REQ`.
|
||||
|
||||
This is **required** for embedding and sync consumers.
|
||||
|
||||
```elixir
|
||||
@spec subscribe(pid(), String.t(), [map()], keyword()) :: {:ok, reference()} | {:error, term()}
|
||||
@spec subscribe(pid(), String.t(), [map()], keyword()) ::
|
||||
{:ok, reference()} | {:error, term()}
|
||||
|
||||
@spec unsubscribe(reference()) :: :ok
|
||||
```
|
||||
|
||||
Required options:
|
||||
|
||||
- `:context` - `%Parrhesia.API.RequestContext{}`
|
||||
|
||||
Subscriber contract:
|
||||
|
||||
```elixir
|
||||
@@ -179,220 +169,233 @@ Subscriber contract:
|
||||
{:parrhesia, :closed, ref, subscription_id, reason}
|
||||
```
|
||||
|
||||
---
|
||||
`subscribe/4` must:
|
||||
|
||||
## 4.4 `Parrhesia.Local.*` wrappers
|
||||
1. validate filters,
|
||||
2. apply read policy,
|
||||
3. emit initial catch-up events in the same order as `REQ`,
|
||||
4. emit exactly one `:eose`,
|
||||
5. register for live fanout until `unsubscribe/1`.
|
||||
|
||||
`Parrhesia.Local.*` remain as convenience API for embedding apps, implemented as thin wrappers:
|
||||
This module does **not** know why a caller wants the stream.
|
||||
|
||||
- `Parrhesia.Local.Auth` -> delegates to `Parrhesia.API.Auth`
|
||||
- `Parrhesia.Local.Events` -> delegates to `Parrhesia.API.Events`
|
||||
- `Parrhesia.Local.Stream` -> delegates to `Parrhesia.API.Stream`
|
||||
- `Parrhesia.Local.Client` -> use-case helpers (posts + private messages)
|
||||
### 5.4 `Parrhesia.API.Admin`
|
||||
|
||||
No business logic in wrappers.
|
||||
Purpose:
|
||||
|
||||
- stable in-process facade for management operations already exposed over HTTP.
|
||||
|
||||
```elixir
|
||||
@spec execute(String.t() | atom(), map(), keyword()) :: {:ok, map()} | {:error, term()}
|
||||
@spec stats(keyword()) :: {:ok, map()} | {:error, term()}
|
||||
@spec health(keyword()) :: {:ok, map()} | {:error, term()}
|
||||
@spec list_audit_logs(keyword()) :: {:ok, [map()]} | {:error, term()}
|
||||
```
|
||||
|
||||
Baseline methods:
|
||||
|
||||
- `ping`
|
||||
- `stats`
|
||||
- `health`
|
||||
- moderation methods already supported by the storage admin adapter
|
||||
|
||||
`stats/1` is relay-level and cheap. `health/1` is liveness/readiness-oriented and may include worker state.
|
||||
|
||||
`API.Admin` is the operator-facing umbrella for management. It may delegate domain-specific work to `API.Identity`, `API.ACL`, and `API.Sync`.
|
||||
|
||||
### 5.5 `Parrhesia.API.Identity`
|
||||
|
||||
Purpose:
|
||||
|
||||
- manage Parrhesia-owned server identity,
|
||||
- expose public identity metadata,
|
||||
- support explicit import and rotation,
|
||||
- keep private key material internal.
|
||||
|
||||
Parrhesia owns a low-level server identity used for relay-to-relay auth and other transport-local security features.
|
||||
|
||||
```elixir
|
||||
@spec get(keyword()) :: {:ok, map()} | {:error, term()}
|
||||
@spec ensure(keyword()) :: {:ok, map()} | {:error, term()}
|
||||
@spec import(map(), keyword()) :: {:ok, map()} | {:error, term()}
|
||||
@spec rotate(keyword()) :: {:ok, map()} | {:error, term()}
|
||||
@spec sign_event(map(), keyword()) :: {:ok, map()} | {:error, term()}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- private key material must never be returned by API,
|
||||
- production deployments should be able to import a configured key,
|
||||
- local/dev deployments may generate on first init if none exists,
|
||||
- identity creation should be eager and deterministic, not lazy on first sync use.
|
||||
|
||||
Recommended boot order:
|
||||
|
||||
1. configured/imported key,
|
||||
2. persisted local identity,
|
||||
3. generate once and persist.
|
||||
|
||||
### 5.6 `Parrhesia.API.ACL`
|
||||
|
||||
Purpose:
|
||||
|
||||
- enforce event/filter ACLs for authenticated principals,
|
||||
- support default-deny sync visibility,
|
||||
- allow dynamic grants for trusted sync peers.
|
||||
|
||||
This is a real authorization layer, not a reuse of moderation allowlists.
|
||||
|
||||
```elixir
|
||||
@spec grant(map(), keyword()) :: :ok | {:error, term()}
|
||||
@spec revoke(map(), keyword()) :: :ok | {:error, term()}
|
||||
@spec list(keyword()) :: {:ok, [map()]} | {:error, term()}
|
||||
@spec check(atom(), map(), keyword()) :: :ok | {:error, term()}
|
||||
```
|
||||
|
||||
Suggested rule shape:
|
||||
|
||||
```elixir
|
||||
%{
|
||||
principal_type: :pubkey,
|
||||
principal: "<server-auth-pubkey>",
|
||||
capability: :sync_read,
|
||||
match: %{
|
||||
"kinds" => [5000],
|
||||
"#r" => ["tribes.accounts.user", "tribes.chat.tribe"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For the first implementation, principals should be authenticated pubkeys only.
|
||||
|
||||
We do **not** need a separate user-vs-server ACL model yet. A sync peer is simply a principal with sync capabilities.
|
||||
|
||||
Initial required capabilities:
|
||||
|
||||
- `:sync_read`
|
||||
- `:sync_write`
|
||||
|
||||
Recommended baseline:
|
||||
|
||||
- ordinary events follow existing relay behavior,
|
||||
- sync traffic is default-deny,
|
||||
- access is lifted only by explicit ACL grants for authenticated server pubkeys.
|
||||
|
||||
### 5.7 `Parrhesia.API.Sync`
|
||||
|
||||
Purpose:
|
||||
|
||||
- manage remote relay sync workers without embedding app-specific replication semantics.
|
||||
|
||||
Parrhesia syncs **events**, not records.
|
||||
|
||||
```elixir
|
||||
@spec put_server(map(), keyword()) ::
|
||||
{:ok, Parrhesia.API.Sync.Server.t()} | {:error, term()}
|
||||
|
||||
@spec remove_server(String.t(), keyword()) :: :ok | {:error, term()}
|
||||
@spec get_server(String.t(), keyword()) ::
|
||||
{:ok, Parrhesia.API.Sync.Server.t()} | :error | {:error, term()}
|
||||
|
||||
@spec list_servers(keyword()) ::
|
||||
{:ok, [Parrhesia.API.Sync.Server.t()]} | {:error, term()}
|
||||
|
||||
@spec start_server(String.t(), keyword()) :: :ok | {:error, term()}
|
||||
@spec stop_server(String.t(), keyword()) :: :ok | {:error, term()}
|
||||
@spec sync_now(String.t(), keyword()) :: :ok | {:error, term()}
|
||||
|
||||
@spec server_stats(String.t(), keyword()) ::
|
||||
{:ok, map()} | :error | {:error, term()}
|
||||
|
||||
@spec sync_stats(keyword()) :: {:ok, map()} | {:error, term()}
|
||||
@spec sync_health(keyword()) :: {:ok, map()} | {:error, term()}
|
||||
```
|
||||
|
||||
`put_server/2` is upsert-style. It covers both add and update.
|
||||
|
||||
Minimum server shape:
|
||||
|
||||
```elixir
|
||||
%{
|
||||
id: "tribes-a",
|
||||
url: "wss://relay-a.example/relay",
|
||||
enabled?: true,
|
||||
auth_pubkey: "<remote-server-auth-pubkey>",
|
||||
filters: [%{"kinds" => [5000], "#r" => ["tribes.accounts.user"]}],
|
||||
mode: :req_stream,
|
||||
auth: %{type: :nip42},
|
||||
tls: %{
|
||||
mode: :required,
|
||||
hostname: "relay-a.example",
|
||||
pins: [
|
||||
%{type: :spki_sha256, value: "<base64-sha256-spki-pin>"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Important constraints:
|
||||
|
||||
- filters are caller-provided and opaque to Parrhesia,
|
||||
- Parrhesia does not inspect `kind: 5000` payload semantics,
|
||||
- Parrhesia may persist peer config and runtime counters,
|
||||
- Parrhesia may reconnect and resume catch-up using generic event cursors,
|
||||
- Parrhesia must expose worker health and basic counters,
|
||||
- remote relay TLS pinning is required,
|
||||
- sync peer auth is bound to a server-auth pubkey, not inferred from event author pubkeys.
|
||||
|
||||
Server identity model:
|
||||
|
||||
- Parrhesia owns its local server-auth identity via `API.Identity`,
|
||||
- peer config declares the expected remote server-auth pubkey,
|
||||
- ACL grants are bound to authenticated server-auth pubkeys,
|
||||
- event author pubkeys remain a separate application concern.
|
||||
|
||||
Initial mode should be `:req_stream`:
|
||||
|
||||
1. run catch-up with `API.Events.query/2`-equivalent client behavior against the remote relay,
|
||||
2. switch to a live subscription,
|
||||
3. ingest received events through local `API.Events.publish/2`.
|
||||
|
||||
Future optimization:
|
||||
|
||||
- `:negentropy` may be added when real NIP-77 reconciliation exists.
|
||||
- It is not required for the first implementation.
|
||||
|
||||
---
|
||||
|
||||
## 5) Server integration plan (critical)
|
||||
## 6. Server Integration
|
||||
|
||||
## 5.1 WebSocket (`Parrhesia.Web.Connection`)
|
||||
### WebSocket
|
||||
|
||||
After decode:
|
||||
- `EVENT` -> `Parrhesia.API.Events.publish/2`
|
||||
- `REQ` -> `Parrhesia.API.Events.query/2`
|
||||
- `REQ` -> `Parrhesia.API.Stream.subscribe/4`
|
||||
- `COUNT` -> `Parrhesia.API.Events.count/2`
|
||||
- `AUTH` keep transport-specific challenge/session flow, but can use `API.Auth.validate_event/1` internally
|
||||
- `AUTH` stays connection-specific, but validation helpers may move to `API.Auth`
|
||||
- `NEG-*` remains transport-specific until Parrhesia has a real reusable NIP-77 engine
|
||||
|
||||
WebSocket keeps responsibility for:
|
||||
- websocket framing
|
||||
- subscription lifecycle per connection
|
||||
- AUTH challenge rotation protocol frames
|
||||
### HTTP management
|
||||
|
||||
## 5.2 HTTP management (`Parrhesia.Web.Management`)
|
||||
- NIP-98 validation via `Parrhesia.API.Auth.validate_nip98/3`
|
||||
- management methods via `Parrhesia.API.Admin`
|
||||
- sync peer CRUD and health endpoints may delegate to `Parrhesia.API.Sync`
|
||||
- identity and ACL management may delegate to `API.Identity` and `API.ACL`
|
||||
|
||||
- NIP-98 header validation via `Parrhesia.API.Auth.validate_nip98/3`
|
||||
- command execution via `Parrhesia.API.Admin` (or existing storage admin adapter via API facade)
|
||||
### Local wrappers
|
||||
|
||||
`Parrhesia.Local.*` remain thin delegates over `Parrhesia.API.*`.
|
||||
|
||||
---
|
||||
|
||||
## 6) High-level client helpers for embedding app use case
|
||||
## 7. Relationship to Sync Profiles
|
||||
|
||||
These helpers are optional and live in `Parrhesia.Local.Client`.
|
||||
This document is intentionally lower-level than `TRIBES-NOSTRSYNC` and `SYNC_DB.md`.
|
||||
|
||||
## 6.1 Public posts
|
||||
Those documents may require:
|
||||
|
||||
```elixir
|
||||
@spec publish_post(Parrhesia.API.Auth.Context.t(), String.t(), keyword()) ::
|
||||
{:ok, Parrhesia.API.Events.PublishResult.t()} | {:error, term()}
|
||||
- `Parrhesia.API.Events.publish/2`
|
||||
- `Parrhesia.API.Events.query/2`
|
||||
- `Parrhesia.API.Stream.subscribe/4`
|
||||
- `Parrhesia.API.Sync.*`
|
||||
|
||||
@spec list_posts(keyword()) :: {:ok, [map()]} | {:error, term()}
|
||||
@spec stream_posts(pid(), keyword()) :: {:ok, reference()} | {:error, term()}
|
||||
```
|
||||
|
||||
`publish_post/3` options:
|
||||
- `:tags`
|
||||
- `:created_at`
|
||||
- `:signer` callback (required unless fully signed event provided)
|
||||
|
||||
Signer contract:
|
||||
|
||||
```elixir
|
||||
(unsigned_event_map -> {:ok, signed_event_map} | {:error, term()})
|
||||
```
|
||||
|
||||
Parrhesia does not store or manage private keys.
|
||||
|
||||
## 6.2 Private messages (giftwrap kind 1059)
|
||||
|
||||
```elixir
|
||||
@spec send_private_message(
|
||||
Parrhesia.API.Auth.Context.t(),
|
||||
recipient_pubkey :: String.t(),
|
||||
encrypted_payload :: String.t(),
|
||||
keyword()
|
||||
) :: {:ok, Parrhesia.API.Events.PublishResult.t()} | {:error, term()}
|
||||
|
||||
@spec inbox(Parrhesia.API.Auth.Context.t(), keyword()) :: {:ok, [map()]} | {:error, term()}
|
||||
@spec stream_inbox(pid(), Parrhesia.API.Auth.Context.t(), keyword()) :: {:ok, reference()} | {:error, term()}
|
||||
```
|
||||
|
||||
Behavior:
|
||||
- `send_private_message/4` builds event template with kind `1059` and `p` tag.
|
||||
- host signer signs template.
|
||||
- publish through `API.Events.publish/2`.
|
||||
- `inbox/2` queries `%{"kinds" => [1059], "#p" => [auth.pubkey]}` with authenticated context.
|
||||
|
||||
---
|
||||
|
||||
## 7) Error model
|
||||
|
||||
Shared API should normalize output regardless of transport.
|
||||
|
||||
Guideline:
|
||||
- protocol/policy rejection -> `{:ok, %{accepted: false, message: "..."}}`
|
||||
- runtime/system failure -> `{:error, term()}`
|
||||
|
||||
Common reason mapping:
|
||||
|
||||
| Reason | Message prefix |
|
||||
|---|---|
|
||||
| `:auth_required` | `auth-required:` |
|
||||
| `:restricted_giftwrap` | `restricted:` |
|
||||
| `:invalid_event` | `invalid:` |
|
||||
| `:duplicate_event` | `duplicate:` |
|
||||
| `:event_rate_limited` | `rate-limited:` |
|
||||
|
||||
---
|
||||
|
||||
## 8) Telemetry
|
||||
|
||||
Emit shared events in API layer (not transport-specific):
|
||||
|
||||
- `[:parrhesia, :api, :publish, :stop]`
|
||||
- `[:parrhesia, :api, :query, :stop]`
|
||||
- `[:parrhesia, :api, :count, :stop]`
|
||||
- `[:parrhesia, :api, :auth, :stop]`
|
||||
|
||||
Metadata:
|
||||
- `traffic_class`
|
||||
- `caller` (`:websocket | :http | :local`)
|
||||
- optional `account_present?`
|
||||
|
||||
Transport-level telemetry can remain separate where needed.
|
||||
|
||||
---
|
||||
|
||||
## 9) Refactor sequence
|
||||
|
||||
### Phase 1: Extract shared API
|
||||
1. Create `Parrhesia.API.Events` with publish/query/count from current `Web.Connection` paths.
|
||||
2. Create `Parrhesia.API.Auth` wrappers for NIP-98/event validation.
|
||||
3. Add API-level tests.
|
||||
|
||||
### Phase 2: Migrate transports
|
||||
1. Update `Parrhesia.Web.Connection` to delegate publish/query/count to `API.Events`.
|
||||
2. Update `Parrhesia.Web.Management` to use `API.Auth`.
|
||||
3. Keep behavior unchanged.
|
||||
|
||||
### Phase 3: Add local wrappers/helpers
|
||||
1. Implement `Parrhesia.Local.Auth/Events/Stream` as thin delegates.
|
||||
2. Add `Parrhesia.Local.Client` post/inbox/send helpers.
|
||||
3. Add embedding documentation.
|
||||
|
||||
### Phase 4: Lock parity
|
||||
1. Add parity tests: WS vs Local API for same inputs and policy outcomes.
|
||||
2. Add property tests for query/count equivalence where feasible.
|
||||
|
||||
---
|
||||
|
||||
## 10) Testing requirements
|
||||
|
||||
1. **Transport parity tests**
|
||||
- Same signed event via WS and API => same accepted/message semantics.
|
||||
2. **Policy parity tests**
|
||||
- Giftwrap visibility and auth-required behavior identical across WS/API/local.
|
||||
3. **Auth tests**
|
||||
- NIP-98 success/failure + account resolver success/failure.
|
||||
4. **Fanout tests**
|
||||
- publish via API reaches local stream subscribers and WS subscribers.
|
||||
5. **Failure tests**
|
||||
- storage failures surface deterministic errors in all transports.
|
||||
|
||||
---
|
||||
|
||||
## 11) Backwards compatibility
|
||||
|
||||
- No breaking change to websocket protocol.
|
||||
- No breaking change to management endpoint contract.
|
||||
- New API modules are additive.
|
||||
- Existing apps can ignore local API entirely.
|
||||
|
||||
---
|
||||
|
||||
## 12) Embedding example flow
|
||||
|
||||
### 12.1 Login/auth
|
||||
|
||||
```elixir
|
||||
with {:ok, auth} <- Parrhesia.API.Auth.validate_nip98(header, method, url,
|
||||
account_resolver: &MyApp.Accounts.resolve_nostr_pubkey/2
|
||||
) do
|
||||
# use auth.pubkey/auth.account in host session
|
||||
end
|
||||
```
|
||||
|
||||
### 12.2 Post publish
|
||||
|
||||
```elixir
|
||||
Parrhesia.Local.Client.publish_post(auth, "hello", signer: &MyApp.NostrSigner.sign/1)
|
||||
```
|
||||
|
||||
### 12.3 Private message
|
||||
|
||||
```elixir
|
||||
Parrhesia.Local.Client.send_private_message(
|
||||
auth,
|
||||
recipient_pubkey,
|
||||
encrypted_payload,
|
||||
signer: &MyApp.NostrSigner.sign/1
|
||||
)
|
||||
```
|
||||
|
||||
### 12.4 Inbox
|
||||
|
||||
```elixir
|
||||
Parrhesia.Local.Client.inbox(auth, limit: 100)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13) Summary
|
||||
|
||||
Yes, this can and should be extracted into a shared API module. The server should consume it too.
|
||||
|
||||
That gives:
|
||||
- one canonical behavior path,
|
||||
- cleaner embedding,
|
||||
- easier testing,
|
||||
- lower long-term maintenance cost.
|
||||
But they must not move application conflict rules or payload semantics into Parrhesia.
|
||||
|
||||
Reference in New Issue
Block a user