Updates
This commit is contained in:
Raven Scott
@@ -1,33 +1,91 @@
|
||||
# hyper-pear-runtime-session
|
||||
|
||||
Production module: Runtime sessions.
|
||||
Track Pear runtime sessions locally: start with metadata, end by id, list active sessions.
|
||||
|
||||
**Protocol:** `pear-runtime-session/v1`
|
||||
**Category:** pear-platform · **Protocol:** `pear-runtime-session/v1` (label) · **Mode:** local
|
||||
|
||||
## When to use
|
||||
|
||||
Session lifecycle.
|
||||
Instrument or gate Pear app lifetimes in one process.
|
||||
|
||||
## When not to use
|
||||
|
||||
Cross-process sync.
|
||||
Distributed session store (compose with gossip modules separately).
|
||||
|
||||
## Quick start
|
||||
|
||||
```js
|
||||
const { HyperPearRuntimeSession } = require('hyper-pear-runtime-session')
|
||||
const m = new HyperPearRuntimeSession()
|
||||
await m.ready()
|
||||
await m.close()
|
||||
const rt = new HyperPearRuntimeSession()
|
||||
await rt.ready()
|
||||
const s = rt.startSession({ app: 'demo' })
|
||||
rt.endSession(s.id)
|
||||
await rt.close()
|
||||
```
|
||||
|
||||
## Docs
|
||||
|
||||
- [docs/api.md](docs/api.md)
|
||||
- [docs/architecture.md](docs/architecture.md)
|
||||
- [docs/api.md](docs/api.md) · [docs/architecture.md](docs/architecture.md)
|
||||
|
||||
## Test
|
||||
|
||||
```bash
|
||||
npm install && npm test
|
||||
npm test
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
| Member | Description |
|
||||
|--------|-------------|
|
||||
| `new HyperPearRuntimeSession(opts?)` | No constructor options used. |
|
||||
| `startSession(meta?)` | Returns `{ id, meta, startedAt, endedAt: null, active: true }`; id from hash slice. |
|
||||
| `endSession(id)` | Sets `active: false`, `endedAt`; throws if missing or already ended. |
|
||||
| `activeSessions()` | Filter `active === true`. |
|
||||
| `getSession(id)` | Record or `null`. |
|
||||
| `getStats()` | `{ started, ended, total, active, protocol, mode: 'local' }`. |
|
||||
| `ready()` / `close()` | Emits `closed`. |
|
||||
|
||||
**Exports:** `HyperPearRuntimeSession`, `HyperP2PPearRuntimeSession`, `PROTOCOL`.
|
||||
|
||||
**Events:** `started`, `ended`, `closed`.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
_sessions Map(id -> session)
|
||||
id = hex(hash(`${Date.now()}-${seq++}`)).slice(0, 8) // 8 hex chars
|
||||
```
|
||||
|
||||
Sequential `_seq` avoids id collision in fast loops.
|
||||
|
||||
## Wire table
|
||||
|
||||
| `type` | Notes |
|
||||
|--------|-------|
|
||||
| — | No network wire; protocol constant for composition docs. |
|
||||
|
||||
## Errors
|
||||
|
||||
- `endSession`: unknown id → `session not found`; already ended → `session already ended`.
|
||||
- Empty `id` on `endSession` / `getSession`.
|
||||
|
||||
## Composition
|
||||
|
||||
- Attach Pear app `meta` (version, channel) at `startSession`.
|
||||
- Metrics: correlate with `hyper-p2p-udx-metrics` per session id in app code.
|
||||
- No gossip—export logs or snapshots externally if needed.
|
||||
|
||||
## Example
|
||||
|
||||
```js
|
||||
const { HyperPearRuntimeSession } = require('hyper-pear-runtime-session')
|
||||
|
||||
const rt = new HyperPearRuntimeSession()
|
||||
await rt.ready()
|
||||
|
||||
const s = rt.startSession({ app: 'demo' })
|
||||
console.log(rt.activeSessions())
|
||||
rt.endSession(s.id)
|
||||
console.log(rt.getStats())
|
||||
await rt.close()
|
||||
```
|
||||
|
||||
@@ -1,26 +1,97 @@
|
||||
# API: hyper-pear-runtime-session
|
||||
|
||||
**Protocol:** `pear-runtime-session/v1` · **Export:** `HyperPearRuntimeSession`
|
||||
**Protocol:** `pear-runtime-session/v1` · **Export:** `HyperPearRuntimeSession`, `HyperP2PPearRuntimeSession`, `PROTOCOL`
|
||||
|
||||
## Overview
|
||||
|
||||
Tracks Pear runtime sessions in-process with opaque ids, optional metadata, and active/ended lifecycle. Local-only — no gossip; suitable for correlating logs and bundle operations within one Bare host.
|
||||
|
||||
## Constructor
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| _(none)_ | — | — | `opts = {}` unused |
|
||||
|
||||
## Methods
|
||||
|
||||
### `startSession(...)`
|
||||
### `startSession(meta?)`
|
||||
|
||||
Domain API.
|
||||
Creates session with random 8-byte hex id from hashed timestamp + sequence.
|
||||
|
||||
### `endSession(...)`
|
||||
- **Returns:** `{ id, meta, startedAt, endedAt: null, active: true }`
|
||||
- **Emits:** `started`
|
||||
|
||||
Domain API.
|
||||
### `endSession(id)`
|
||||
|
||||
### `activeSessions(...)`
|
||||
Marks session ended.
|
||||
|
||||
Domain API.
|
||||
- **Returns:** updated session
|
||||
- **Throws:** `session not found: ${id}`; `session already ended: ${id}`
|
||||
- **Emits:** `ended`
|
||||
|
||||
### `activeSessions()`
|
||||
|
||||
### `getStats()` / `ready()` / `close()`
|
||||
- **Returns:** array of sessions where `active === true`
|
||||
|
||||
Lifecycle helpers.
|
||||
### `getSession(id)`
|
||||
|
||||
- **Returns:** session or `null`
|
||||
- **Throws:** `assertNonEmpty` on `id`
|
||||
|
||||
### `ready()` / `close()`
|
||||
|
||||
Immediate `ready()`. `close()` emits `closed`.
|
||||
|
||||
## Events
|
||||
|
||||
| Event | Payload |
|
||||
|-------|---------|
|
||||
| `started` | session object |
|
||||
| `ended` | session object |
|
||||
| `closed` | — |
|
||||
|
||||
## getStats()
|
||||
|
||||
| Field | Meaning |
|
||||
|-------|---------|
|
||||
| `started` / `ended` | lifecycle counters |
|
||||
| `total` | all sessions in map |
|
||||
| `active` | count of active sessions |
|
||||
| `protocol` | `pear-runtime-session/v1` |
|
||||
| `mode` | `local` |
|
||||
|
||||
## Wire
|
||||
|
||||
No wire messages.
|
||||
|
||||
| type | fields | notes |
|
||||
|------|--------|-------|
|
||||
| — | — | local-only |
|
||||
|
||||
## Errors
|
||||
|
||||
`assertNonEmpty` for id lookups. Session state errors use exact `Error` strings above.
|
||||
|
||||
See [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
|
||||
|
||||
## P2P
|
||||
|
||||
Local-only.
|
||||
Not used. Pair with gossip modules only at application layer (attach session id to gossip meta).
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
cd modules/pear-platform/hyper-pear-runtime-session && npm test
|
||||
```
|
||||
|
||||
## Composition
|
||||
|
||||
`hyper-bare-bundle-bridge`, `hyper-pear-update-gossip`, `hyper-p2p-session-rotation` for token rotation after session end.
|
||||
|
||||
## Example
|
||||
|
||||
See [`examples/basic.js`](../examples/basic.js).
|
||||
|
||||
## See also
|
||||
|
||||
[`docs/architecture.md`](architecture.md).
|
||||
|
||||
@@ -1,11 +1,31 @@
|
||||
# Architecture: hyper-pear-runtime-session
|
||||
|
||||
**Protocol:** `pear-runtime-session/v1` · **Category:** pear-platform · **Mode:** local-only
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
App --> Sess[HyperPearRuntimeSession]
|
||||
Sess --> Map[_sessions Map]
|
||||
```
|
||||
|
||||
## Wire messages
|
||||
|
||||
| type | fields | direction | behavior |
|
||||
|------|--------|-----------|----------|
|
||||
| — | — | — | Local-only |
|
||||
| type | direction | fields | behavior |
|
||||
|------|-----------|--------|----------|
|
||||
| — | — | — | No network protocol; id constant for module registry |
|
||||
|
||||
## State
|
||||
## State model
|
||||
|
||||
In-memory structures; gossip via `initModuleSwarm` / `gossipSend` when P2P enabled.
|
||||
- `_sessions`: `Map<id, session>`
|
||||
- `_seq`: monotonic counter for id generation
|
||||
- `_stats`: `started`, `ended`
|
||||
|
||||
## Sequence
|
||||
|
||||
1. `startSession` → hash-based id → `emit('started')`
|
||||
2. `endSession` → flip `active`, set `endedAt`
|
||||
3. `getStats` aggregates active count
|
||||
|
||||
## Composition
|
||||
|
||||
`hyper-bare-bundle-bridge`, `hyper-pear-update-gossip`.
|
||||
|
||||
Reference in New Issue
Block a user