@mcp-abap-adt/connection 8.0.0 → 8.0.1

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [8.0.1] - 2026-09-08
+
+**Documentation only — 7.0.0 and 8.0.0 shipped without their migration note.**
+
+Both majors are already on npm, and `docs/` travels in the tarball, so the
+installed package described the pre-7.0.0 connection: no request id, no
+profiling, no `flushGoodbye`, and no word on what a consumer on 6.x must
+change. This release carries the documentation those two releases owed and
+changes no code.
+
+### Documentation
+
+- `docs/MIGRATION-8.0.md` (new): what a consumer on 6.x does about the
+  `IAdtWireResponse` return of `makeAdtRequest`, the capability atoms the
+  class now declares, and the two headers every request now carries.
+- `docs/STATEFUL_SESSION_GUIDE.md`: the session type is the connection's —
+  `x-sap-adt-sessiontype: stateful` is added by the transport, not by a
+  caller's headers — and `flushGoodbye` is how a caller waits for the
+  goodbye.
+- `README.md` and `docs/INDEX.md` point at both.
+
 ## [8.0.0] - 2026-09-08
 
 **A consumer holding the contract can now do what the connection could always do.**
@@ -1513,7 +1534,8 @@ const connection = createAbapConnection(config, logger);
 - JWT token refresh now properly handles connection errors (401/403 during initial connect)
 - Permission errors (403 with "ExceptionResourceNoAccess") no longer trigger JWT refresh loops
 - Proper separation: base class handles HTTP/session, concrete classes handle auth-specific errors
-[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v8.0.0...HEAD
+[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v8.0.1...HEAD
+[8.0.1]: https://github.com/fr0ster/mcp-abap-connection/compare/v8.0.0...v8.0.1
 [8.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v7.0.0...v8.0.0
 [7.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v6.1.0...v7.0.0
 [6.0.1]: https://github.com/fr0ster/mcp-abap-connection/compare/v6.0.0...v6.0.1

package/README.md

@@ -34,7 +34,9 @@ The package uses a clean separation of concerns:
 
 - **`AbstractAbapConnection`** (abstract, internal only):
   - Common HTTP request logic
-  - Session lifecycle: `connect()` / `disconnect()`, admission, lock windows, teardown draining
+  - Session lifecycle: `connect()` / `disconnect()` / `flushGoodbye()`, admission, lock windows, teardown draining
+  - Capability atoms a consumer narrows to, rather than casting to a connector class:
+    `ISessionLifecycleAware`, `ICriticalSection`, `IRequestProfiling`
   - Session management (cookies, CSRF tokens)
   - CSRF token fetching with retry
   - Auth-agnostic - knows nothing about Basic or JWT

package/docs/INDEX.md

@@ -15,6 +15,7 @@ mcp-abap-connection/
 │   ├── INSTALLATION.md             # Setup and installation guide
 │   ├── USAGE.md                    # API documentation and examples
 │   ├── MIGRATION-2.0.md            # Moving to the explicit session lifecycle
+│   ├── MIGRATION-8.0.md            # request headers leave the stateful branch; onto interfaces 39; flushGoodbye
 │   ├── MIGRATION-6.0.md            # the factory and the per-credential classes go; RFC is a transport
 │   ├── MIGRATION-4.0.md            # JWT error classification: 401 refreshes, 403 propagates
 │   ├── SCOPE.md                    # What this package does and does not own
@@ -44,6 +45,7 @@ mcp-abap-connection/
 - 🔑 [JWT Auth Tools](./JWT_AUTH_TOOLS.md) - CLI tool for browser-based authentication
 
 ### Upgrading
+- 🚚 [Migrating to 7.0.0 and 8.0.0](./MIGRATION-8.0.md) - `sap-adt-request-id` and `X-sap-adt-profiling` on every request, `x-sap-security-session: use` on cloud, the contracts floor at 39, and `flushGoodbye()`
 - 🚚 [Migrating to 6.0.0](./MIGRATION-6.0.md) - the factory and the per-credential classes are removed; the RFC wire is a transport you hand to the on-prem connector
 - 🧱 [Migrating to 4.0.0](./MIGRATION-4.0.md) - JWT error classification: a 401 refreshes, a 403 propagates with the server's message
 - 🧱 [Migrating to 2.0.0](./MIGRATION-2.0.md) - The explicit session lifecycle: `connect()` is required

package/docs/MIGRATION-8.0.md

@@ -0,0 +1,171 @@
+# Migration to 7.0 and 8.0
+
+Two majors, and **no code of yours has to change for either**. One alters what
+goes on the wire; the other moves the contracts floor and makes methods you
+already had reachable through the types you already hold.
+
+If you build against `@mcp-abap-adt/interfaces` and never cast to a connector
+class, there is nothing to do but install.
+
+## 7.0 — headers that belong to the request stop belonging to the session
+
+Three headers used to be written together, inside the stateful branch:
+
+```ts
+if (this.sessionMode === 'stateful') {
+  requestHeaders['x-sap-adt-sessiontype'] = 'stateful';
+  requestHeaders['sap-adt-request-id'] = randomUUID().replace(/-/g, '');
+  requestHeaders['X-sap-adt-profiling'] = 'server-time';
+}
+```
+
+Only the first belongs there. A request id identifies the **request**, and
+asking the server to report its own processing time is not a property of the
+session either. Eclipse sends both on everything — measured on ADT 3.60.0, a
+stateless source `PUT` carries them and no session type at all.
+
+It stayed invisible while every write ran inside a lock window. Once
+`@mcp-abap-adt/adt-clients` narrowed stateful to the `LOCK` and the `UNLOCK`,
+the writes silently lost two headers: of 792 requests in a full run, 99 carried
+a request id and **693 carried neither**.
+
+### What changed for you
+
+| | |
+|---|---|
+| `sap-adt-request-id` | now on every request, fresh each time |
+| `X-sap-adt-profiling` | now on every request, from a settable default |
+| `x-sap-security-session: use` | **cloud only**, on every request once a session exists |
+| `x-sap-adt-sessiontype` | unchanged — still the only one that varies with the mode |
+
+Nothing in the type surface moved. The major is for the wire: every request
+looks different in an SAP trace, and a system that reacts badly to either should
+be findable by version rather than by reading a dump.
+
+### Your own headers win
+
+Both new headers are **defaults**. A caller who names either in
+`options.headers` keeps their value, matched without case:
+
+```ts
+await conn.makeAdtRequest({
+  url, method: 'GET', timeout: 30_000,
+  headers: { 'sap-adt-request-id': myCorrelationId },   // kept, not replaced
+});
+```
+
+That is not hypothetical: `adt-clients` passes its own id to
+`getDiscovery({ requestId })` so the id it logs is the id on the wire.
+
+### Turning the profiling off
+
+```ts
+conn.setProfilingRequest(null);          // ask for nothing
+conn.setProfilingRequest('server-time'); // the default, and what Eclipse asks for
+```
+
+Nothing in this package reads the `server-time=…` that comes back. An
+investigation does, though — the unit is **microseconds**, which a trial's
+unpublish job settled by answering `server-time=132512547` on a request that
+takes about 133 seconds.
+
+## 8.0 — onto interfaces 39.0.0, and the atoms are declared
+
+### The floor
+
+`@mcp-abap-adt/interfaces` moves from `^21.0.0` to `^39.0.0`. Install it
+alongside; a consumer pinned below 39 cannot have both.
+
+Seventeen majors, and the whole migration inside this package was eight compiler
+errors in one file — `makeAdtRequest` returning `IAdtWireResponse<T, D>` rather
+than `IAdtResponse<T, D>`, and `isNetworkError` coming home because interfaces
+stopped emitting code in 29.0.0.
+
+**If you deduplicate nothing else, deduplicate this.** Two copies of the
+contracts in one graph are structurally identical and do not compare equal, so
+they produce errors that read as impossible.
+
+```
+npm ls @mcp-abap-adt/interfaces     # should print one version, deduped
+```
+
+### `flushGoodbye()` — the half of `disconnect()` that was missing
+
+`disconnect()` dispatches the logoff and does not await it, on purpose: a
+goodbye carries no request timeout, and a server that never answers must not
+hold a teardown open.
+
+That is right for a teardown and wrong for a **reconnect**:
+
+```ts
+await conn.disconnect();
+await conn.flushGoodbye();   // give the goodbye its budget to finish first
+await conn.connect();
+```
+
+Without the middle line, the next session opens while the previous one's goodbye
+is still being assembled and the server keeps both. Measured on E19 through a
+test harness that recycled the session after each test: **a new ABAP session
+every one to two seconds for a whole run, none released**, each living to its
+own thirty-minute idle timeout.
+
+**The budget bounds the waiting, not the overlap.** If the goodbye finishes in
+time there is no overlap; if it does not, you proceed and it stays outstanding
+for as long as it takes. A return is not a confirmation and not even of
+dispatch.
+
+Calling `disconnect()` twice is **not** a substitute — a repeat call does not
+wait either.
+
+### Reaching the controls through the contract
+
+`beginCriticalSection()`, `setProfilingRequest()` and `flushGoodbye()` all
+existed before. What changed is that a consumer can reach them without a cast:
+`AbapConnection` is `IAbapConnection`, and these now live on capability atoms
+that this connection declares.
+
+```ts
+import type {
+  IAbapConnection,
+  ICriticalSection,
+  IRequestProfiling,
+  ISessionLifecycleAware,
+} from '@mcp-abap-adt/interfaces';
+
+function protectTheWindow(conn: IAbapConnection & ICriticalSection) {
+  conn.beginCriticalSection();
+  try {
+    // the ordinary per-request deadline does not apply in here
+  } finally {
+    conn.endCriticalSection();
+  }
+}
+```
+
+`flushGoodbye` is a member of `ISessionLifecycleAware`, not an atom of its own:
+waiting for the goodbye is not a separate capability from sending it.
+
+### One thing to know about `implements`
+
+TypeScript is structural. Removing an atom from a class's `implements` list
+changes nothing for a consumer — the class still has the methods and narrowing
+still succeeds. What the clause buys is the compiler checking the class *against*
+the contract in the other direction: remove `beginCriticalSection` itself and it
+is `TS2420`.
+
+Worth knowing before writing a guard that tests the clause rather than the
+method.
+
+### `IRenewableCredential` is an atom now
+
+Not this package's change, but it lands with the floor. Renewing is something a
+credential can also do, not a kind of credential, so a guard that narrowed to
+`IRenewableCredential` alone now hands the caller something that renews and
+cannot authenticate:
+
+```ts
+// before
+function isRenewable(c: IAuthProvider): c is IRenewableCredential
+// after
+function isRenewable(c: IAuthProvider): c is IAuthProvider & IRenewableCredential
+```

package/docs/STATEFUL_SESSION_GUIDE.md

@@ -120,6 +120,22 @@ authentication answer. A 403 never did this: it is an authorization answer, not
 If you decide the refusal meant a stale token, `renew()` and reconnect are yours to call — and a
 reconnect is a NEW session, so do it outside a lock window rather than inside one.
 
+**Wait for the goodbye before opening the next one.** `disconnect()` dispatches the logoff and does
+not await it, so a reconnect otherwise opens the next session while the previous one's goodbye is
+still being assembled, and the server keeps both:
+
+```typescript
+await conn.disconnect();
+await conn.flushGoodbye();   // give the goodbye its budget to finish first
+await conn.connect();
+```
+
+Measured on E19 through a harness that recycled the session after each test: a new ABAP session
+every one to two seconds for a whole run, none released, each living to its own thirty-minute idle
+timeout. The budget bounds the waiting, not the overlap — if the goodbye finishes in time there is
+none, and if it does not you proceed while it stays outstanding. Calling `disconnect()` again is not
+a substitute: a repeat call does not wait either.
+
 ---
 
 ## Interaction With ADT Clients
@@ -189,6 +205,13 @@ lock is still very much held. That — not any teardown — is why
 `beginCriticalSection()` raises the effective timeout to a large ceiling for the
 duration of a `lock → modify → unlock` chain.
 
+Since 8.0.0 you reach it through the contract rather than the class: it is
+`ICriticalSection` in `@mcp-abap-adt/interfaces`, which this connection declares.
+What it promises is narrow and worth stating exactly — inside a section the
+*ordinary* per-request deadline does not apply. Not that no request can be cut
+short: the ceiling is `SAP_TIMEOUT_CRITICAL`, ten minutes by default, and a
+socket ends a request whatever a contract says.
+
 ### Two sessions, and they are not the same thing
 
 There are two sessions here, and they are not the same thing:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/connection",
-  "version": "8.0.0",
+  "version": "8.0.1",
   "description": "ABAP connection layer for MCP ABAP ADT server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",