@mcp-abap-adt/connection 1.10.2 → 3.0.0

package/dist/session/SessionLifecycle.js

@@ -1,24 +1,20 @@
 "use strict";
 /**
  * Owns the session lifecycle: what state the session is in, who may use it, and
- * when it is safe to tear it down.
+ * when it stops being current.
  *
  * Deliberately knows nothing about SAP, HTTP, RFC, cookies or ADT. Identities
- * are opaque maps of name → value that someone else computed; windows are
- * opaque labels. That is what makes this unit testable without a server, and it
- * is where the hard part of the design lives: ordering, admission, deadlines.
+ * are opaque maps of name → value that someone else computed. That is what makes
+ * this unit testable without a server, and it is where the hard part lives:
+ * ordering, admission, and telling one session from the next.
  *
- * Design: docs/superpowers/specs/2026-07-27-session-lifecycle-design.md in
+ * Design: docs/superpowers/specs/2026-07-31-teardown-policy-design.md in
  * @mcp-abap-adt/adt-clients.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionLifecycle = exports.ADT_SESSION_ERROR = void 0;
+exports.SessionLifecycle = void 0;
 exports.sessionError = sessionError;
-exports.ADT_SESSION_ERROR = {
-    NOT_CONNECTED: 'ADT_NOT_CONNECTED',
-    SESSION_REPLACED: 'ADT_SESSION_REPLACED',
-    RELEASE_PENDING: 'ADT_RELEASE_PENDING',
-};
+const interfaces_1 = require("@mcp-abap-adt/interfaces");
 function sessionError(code, message) {
     const error = new Error(message ?? code);
     error.code = code;
@@ -28,28 +24,14 @@ class SessionLifecycle {
     state = 'disconnected';
     fingerprint = new Map();
     epoch = 0;
+    generation = 0;
     teardownPending = false;
-    teardownLostSession = false;
-    teardownAt = null;
-    /** Set at expiry: admission is shut regardless of open windows. */
-    admissionForcedShut = false;
-    windows = new Map();
     inFlight = 0;
     tail = Promise.resolve();
     tailKind = null;
     tailPromise = null;
-    waiters = [];
-    ceilingMs;
-    now;
-    constructor(options = {}) {
-        this.ceilingMs = options.ceilingMs ?? 600_000;
-        this.now = options.now ?? (() => Date.now());
-    }
     // ---------------------------------------------------------------- state ---
-    /**
-     * Whether a caller may start work. False throughout a teardown, including
-     * while a grandfathered window is still finishing: finishing is not starting.
-     */
+    /** Whether a caller may start work. False throughout a pending teardown. */
     get connected() {
         return this.state === 'connected' && !this.teardownPending;
     }
@@ -65,42 +47,55 @@ class SessionLifecycle {
     get teardownEpoch() {
         return this.epoch;
     }
-    /** One entry per open window, abandoned ones included. */
-    get openWindows() {
-        return [...this.windows.values()].map((w) => w.label);
+    /**
+     * Which session is current, counted from zero.
+     *
+     * Two counters answer two different questions, and one cannot do both:
+     *
+     * - `epoch` — did the CALLER ask to stop? It moves only on a caller-initiated
+     *   teardown, because a recovery must not cancel itself.
+     * - `generation` — is this still the session you were issued against? It moves
+     *   on every change of which session is current, however caused.
+     *
+     * A fence built on `epoch` misses every internal teardown: after a session
+     * loss and a successful recovery, requests from the dead session carry the
+     * same epoch as the new one and sail straight through.
+     */
+    get sessionGeneration() {
+        return this.generation;
     }
     /**
      * Publishes a freshly established session, which also ENDS any teardown that
      * was pending: the flags describe the session being torn down, and this is a
      * different one. Without this, `connect()` after `disconnect()` — which the
      * design allows explicitly — leaves the lifecycle permanently unusable.
-     *
-     * Windows are dropped for the same reason: they belonged to the old session,
-     * nothing here can close them, and a teardown that gave up on them has
-     * already carried their labels out in its report. Keeping them would make
-     * every future drain re-report locks from a session that no longer exists.
      */
     markConnected(fingerprint = new Map()) {
         this.state = 'connected';
         this.fingerprint = new Map(fingerprint);
         this.teardownPending = false;
-        this.teardownLostSession = false;
-        this.admissionForcedShut = false;
-        this.teardownAt = null;
-        this.windows.clear();
-        this.wake();
+        this.generation += 1;
+    }
+    /**
+     * Drops the tracked identity without touching state or generation.
+     *
+     * For a session the caller discarded ON PURPOSE — a credential renewal, a
+     * cache invalidation. The next fingerprint then reads as `established` rather
+     * than `replaced`, which is the truth: nothing was taken from us.
+     */
+    forgetIdentity() {
+        this.fingerprint.clear();
     }
     markDisconnected() {
         this.state = 'disconnected';
         this.fingerprint.clear();
-        this.wake();
     }
     /**
      * Classifies a freshly observed fingerprint.
      *
      * Additive: a name appearing where none was tracked is `established`, never
      * `replaced` — otherwise the identifier a LOCK response adds would read as a
-     * new session and blow up the window it just opened.
+     * new session and condemn the operation it just covered.
      */
     observe(fingerprint) {
         let established = false;
@@ -118,23 +113,9 @@ class SessionLifecycle {
         return established ? 'established' : 'unchanged';
     }
     // ------------------------------------------------------------ admission ---
-    /** True while an already-open window is allowed to finish its work. */
-    get finishingWindowOpen() {
-        return (this.teardownPending &&
-            !this.teardownLostSession &&
-            !this.admissionForcedShut &&
-            this.windows.size > 0);
-    }
-    get admits() {
-        if (this.state !== 'connected')
-            return false;
-        if (!this.teardownPending)
-            return true;
-        return this.finishingWindowOpen;
-    }
     assertUsable() {
-        if (!this.admits) {
-            throw sessionError(exports.ADT_SESSION_ERROR.NOT_CONNECTED);
+        if (this.state !== 'connected' || this.teardownPending) {
+            throw sessionError(interfaces_1.ADT_SESSION_ERROR.NOT_CONNECTED);
         }
     }
     /** Asserts usability and counts the request in, in one synchronous step. */
@@ -142,107 +123,52 @@ class SessionLifecycle {
         this.assertUsable();
         this.inFlight += 1;
         const epoch = this.epoch;
+        const generation = this.generation;
         let released = false;
         return {
             epoch,
+            generation,
             release: () => {
                 if (released)
                     return;
                 released = true;
                 this.inFlight -= 1;
-                this.wake();
             },
         };
     }
-    // -------------------------------------------------------------- windows ---
+    /** How many admitted requests have not settled. Diagnostics only — nothing waits on it. */
+    get requestsInFlight() {
+        return this.inFlight;
+    }
     /**
-     * A lock outlives the request that takes it, so it is the one thing a pending
-     * teardown refuses outright.
+     * Whether a lease may still touch shared state.
+     *
+     * A request outliving its session is ordinary now that a teardown does not
+     * wait: its response must not write cookies over a newer session's, and must
+     * not be read as a replacement — which would raise a session-lost teardown
+     * against a session that is perfectly healthy.
      */
-    beginWindow(label) {
-        if (this.state !== 'connected' || this.teardownPending) {
-            throw sessionError(exports.ADT_SESSION_ERROR.NOT_CONNECTED);
-        }
-        const token = Symbol(label);
-        this.windows.set(token, { label, abandoned: false });
-        return token;
-    }
-    /** A token matching no open window is ignored: double close, foreign token. */
-    endWindow(token) {
-        if (!this.windows.delete(token))
-            return;
-        this.wake();
+    isCurrent(lease) {
+        return lease.generation === this.generation;
     }
     // ------------------------------------------------------------- teardown ---
     beginTeardown({ origin, sessionLost }) {
-        if (!this.teardownPending) {
-            this.teardownAt = this.now();
-        }
         this.teardownPending = true;
         if (origin === 'caller') {
             this.epoch += 1;
         }
+        // The moment a session stops being current is the moment leases against it
+        // go stale — whether or not a replacement exists yet. Counting only at
+        // markConnected() leaves the gap between a teardown and the next connect,
+        // where a late response would write into state just cleared.
+        this.generation += 1;
         if (sessionLost) {
-            this.teardownLostSession = true;
-            // Nothing can finish over a session that is gone: give up on every window
-            // now, and drop the identity so a later comparison sees the change.
-            for (const entry of this.windows.values())
-                entry.abandoned = true;
             this.fingerprint.clear();
         }
-        this.wake();
     }
     get teardownRequested() {
         return this.teardownPending;
     }
-    /**
-     * Resolves when nothing is in flight and no window is still worth waiting
-     * for. Bounded by the ceiling measured from the teardown request — absolute,
-     * never extended by request activity.
-     *
-     * On expiry, before resolving and without yielding in between: shuts
-     * admission, gives up on the remaining windows, then waits once more for the
-     * already-admitted requests to settle.
-     */
-    async drain() {
-        // `??`, not `||`: a teardown requested at timestamp 0 is a real teardown,
-        // and treating it as absent would restart the ceiling from drain() — making
-        // the deadline relative to the wrong event, which is the sliding behaviour
-        // this design rejects.
-        const deadline = (this.teardownAt ?? this.now()) + this.ceilingMs;
-        while (this.inFlight > 0 || this.liveWindows > 0) {
-            const remaining = deadline - this.now();
-            if (remaining <= 0)
-                break;
-            await this.changed(remaining);
-        }
-        if (this.inFlight === 0 && this.liveWindows === 0) {
-            return { abandonedWindows: this.abandonedLabels() };
-        }
-        // Expiry. Synchronous, before any await: no request may enter after this.
-        this.admissionForcedShut = true;
-        for (const entry of this.windows.values())
-            entry.abandoned = true;
-        while (this.inFlight > 0) {
-            await this.changed();
-        }
-        return { abandonedWindows: this.abandonedLabels() };
-    }
-    get liveWindows() {
-        let live = 0;
-        for (const entry of this.windows.values())
-            if (!entry.abandoned)
-                live += 1;
-        return live;
-    }
-    abandonedLabels() {
-        const labels = new Set();
-        for (const entry of this.windows.values()) {
-            if (entry.abandoned)
-                labels.add(entry.label);
-        }
-        return [...labels];
-    }
     // ---------------------------------------------------------- transitions ---
     /**
      * Runs a transition on the serializing tail.
@@ -252,8 +178,7 @@ class SessionLifecycle {
      * when nothing is queued behind it, so a join can never overtake a queued
      * transition of another kind. `recover` and `cleanup` never join and are
      * never joined: a recovery carries its own request's baseline, and an
-     * internal cleanup owes its result to nobody while a caller's teardown owes a
-     * report.
+     * internal cleanup owes its result to nobody.
      */
     transition(kind, run) {
         const joinable = kind === 'connect' || kind === 'disconnect';
@@ -273,29 +198,5 @@ class SessionLifecycle {
         queued.then(settle, settle);
         return queued;
     }
-    // ----------------------------------------------------------- internals ---
-    wake() {
-        const waiters = this.waiters;
-        this.waiters = [];
-        for (const resolve of waiters)
-            resolve();
-    }
-    changed(timeoutMs) {
-        return new Promise((resolve) => {
-            let done = false;
-            const finish = () => {
-                if (done)
-                    return;
-                done = true;
-                resolve();
-            };
-            this.waiters.push(finish);
-            if (timeoutMs !== undefined) {
-                const timer = setTimeout(finish, timeoutMs);
-                if (typeof timer.unref === 'function')
-                    timer.unref();
-            }
-        });
-    }
 }
 exports.SessionLifecycle = SessionLifecycle;

package/docs/INDEX.md

@@ -0,0 +1,106 @@
+# Documentation Index
+
+**Package:** `@mcp-abap-adt/connection`  
+**Version:** see [CHANGELOG.md](../CHANGELOG.md) — kept there rather than
+duplicated here, where it went stale by eight minor versions.
+
+## Package Structure
+
+```
+mcp-abap-connection/
+├── README.md                 # Main package documentation
+├── CHANGELOG.md             # Version history and changes
+├── docs/                    # Detailed documentation
+│   ├── INDEX.md                    # This file - documentation overview
+│   ├── INSTALLATION.md             # Setup and installation guide
+│   ├── USAGE.md                    # API documentation and examples
+│   ├── MIGRATION-2.0.md            # Moving to the explicit session lifecycle
+│   ├── SCOPE.md                    # What this package does and does not own
+│   ├── STATEFUL_SESSION_GUIDE.md   # Stateful requests and lock windows
+│   └── JWT_AUTH_TOOLS.md           # CLI tool for authentication
+├── examples/               # Working code examples
+│   ├── README.md          # Examples overview
+│   └── basic-connection.js # Simple connection example
+├── bin/                   # CLI tools
+│   └── sap-abap-auth.js  # JWT authentication CLI
+└── src/                  # Source code
+    ├── connection/       # Connection classes
+    ├── config/          # Configuration utilities
+    ├── utils/           # Helper functions
+    └── __tests__/       # Unit tests
+```
+
+## Quick Links
+
+### Getting Started
+- 📦 [Installation Guide](./INSTALLATION.md) - How to install and set up the package
+- 📚 [Usage Guide](./USAGE.md) - Basic usage and comprehensive API documentation
+- 📖 [Main README](../README.md) - Package overview and quick start
+- 🧭 [Scope and Boundaries](./SCOPE.md) - What this package does (and does not), sibling packages, and why there is no RFC to cloud
+
+### Core Features
+- 🔑 [JWT Auth Tools](./JWT_AUTH_TOOLS.md) - CLI tool for browser-based authentication
+
+### Version Information
+- 📋 [CHANGELOG](../CHANGELOG.md) - Complete version history, including what the latest release changed
+
+### Examples
+- 📁 [Examples Overview](../examples/README.md) - All available examples
+- 🔌 [Basic Connection](../examples/basic-connection.js) - Simple connection setup
+
+## Documentation by Topic
+
+### Authentication
+- **Basic Auth**: [USAGE.md - Basic Authentication](./USAGE.md#basic-authentication-on-premise)
+- **JWT/OAuth2**: [USAGE.md - JWT Authentication](./USAGE.md#jwt-authentication-cloudbtp)
+- **Token Refresh**: Handled by `@mcp-abap-adt/auth-broker` package (removed in 0.2.0)
+- **CLI Tool**: [JWT_AUTH_TOOLS.md](./JWT_AUTH_TOOLS.md)
+
+### Session Management
+- **Overview**: [USAGE.md - Session Management](./USAGE.md#session-management)
+- **Stateful Mode**: Use `setSessionType('stateful')` for session headers
+- **Session State Persistence**: Handled by `@mcp-abap-adt/auth-broker` package
+- **API Methods**:
+  - `getSessionId()` - Get current session ID (auto-generated UUID)
+  - `setSessionType()` - Switch between stateful/stateless modes
+
+### API Reference
+- **Connection Interface**: [USAGE.md - API Reference](./USAGE.md#api-reference)
+- **Configuration Types**: [USAGE.md - Configuration Types](./USAGE.md#configuration-types)
+- **Factory Function**: `createAbapConnection()`
+- **Connection Classes**: `BaseAbapConnection`, `JwtAbapConnection`
+
+## Version Highlights
+
+See [CHANGELOG.md](../CHANGELOG.md). This section used to restate it and drifted
+eight minor versions behind — a second copy of a changelog is a changelog that
+is wrong.
+
+## Documentation Standards
+
+### File Organization
+- **README.md** - Package overview, quick start, basic API
+- **CHANGELOG.md** - All changes, following [Keep a Changelog](https://keepachangelog.com/)
+- **docs/** - Detailed documentation, tutorials, guides
+- **examples/** - Working code examples with README
+
+### Naming Conventions
+- `UPPERCASE.md` - Main documentation files (README, CHANGELOG)
+- `PascalCase.md` - Detailed guides in docs/ folder
+- `kebab-case.js` - Example files
+
+### Content Guidelines
+- Keep README concise, link to detailed docs
+- Include working code examples
+- Document environment variables and configuration
+- Provide troubleshooting sections
+- Show both success and error handling
+
+## Contributing Documentation
+
+When adding new features:
+1. Update CHANGELOG.md with changes
+2. Add usage examples to USAGE.md
+3. Create working examples in examples/
+4. Update README.md if API changes
+5. Add troubleshooting to relevant guide