@mcp-abap-adt/connection 4.0.0 → 6.0.0

package/CHANGELOG.md

@@ -7,6 +7,410 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.0.0] - 2026-08-24
+
+The wire owns what is the wire's, and the factory and per-credential classes are
+gone. See [Migration to 6.0](./docs/MIGRATION-6.0.md).
+
+### Added
+
+- **The transport axis is complete and public.** `IAdtTransport` now covers
+  everything true of a wire — carrying a request, addressing it, establishing
+  itself, and whatever session state it keeps — and both ends are objects:
+  `HttpTransport` and `RfcTransport`. `IAdtEstablishContext`, `IRfcConversation`
+  and `RfcConnectionParams` are exported, so a caller handed a seam can name it.
+
+- **`rfcConversationFrom(config)`** — the front door to the RFC wire. Derives
+  `ashost` from the url and `sysnr` from the HTTP port (`80XX` → `XX`, with
+  `SAP_SYSNR` overriding), and loads the SAP NW RFC SDK only when a conversation
+  opens, so a machine without it fails at `connect()` rather than at
+  construction.
+
+- **`RfcTransport` supplies a default `Accept`.** axios adds one over HTTP and
+  nobody had noticed; ADT refuses a request without it with
+  `400 ExceptionResourceBadRequest: Accept header missing`.
+
+### Changed
+
+- **The on-prem connector works over RFC.** It did not, at all. Measured against
+  a real system, three blockers stood one behind the other, all of them HTTP
+  assumptions in the class every connector shares: the CSRF fetch handed
+  `SADT_REST_RFC_ENDPOINT` an absolute URL and dumped it with
+  `STRING_OFFSET_TOO_LARGE`; that endpoint returns no `x-csrf-token` however it
+  is asked, so the exchange could not succeed; and the session fingerprint was a
+  scan for a `SAP_SESSIONID` cookie, so a wire that issues none read as a
+  connection the server had opened no session for.
+
+  The base class did not merely check for cookies — it DEFINED a session as one.
+
+- **`AbstractAbapConnection` keeps the lifecycle and nothing else** (1989 → ~1620
+  lines): the transition queue, teardown epochs, session generations, critical
+  sections, stale-request fencing, 401 classification, the identity policy, and
+  the promise that `disconnect()` settles. Cookies, the cookie jar, the CSRF
+  exchange, affinity headers, axios and addressing all moved to the wire that
+  has them. There is no `if (transport is rfc)` anywhere.
+
+- **A credential refused surfaces** rather than being renewed behind the caller —
+  on `connect()` and on the request path alike. Renewal is the provider's, and it
+  happens on an expiry the provider can see, on every call that asks for a header.
+  See *Removed*, below: nothing here answers a 401 any more.
+
+### Changed — BREAKING
+
+- **The base classes ask nothing.** `AbstractAbapConnection` and
+  `CredentialAbapConnection` contain no config-driven conditional, no optional-member
+  call, and no dispatch on a type or a shape. What a collaborator can do is stated by
+  its type, not discovered at runtime:
+
+  - `IAdtTransport.open()` / `close()` are required — a wire with nothing to open
+    writes an empty method, which is true of it;
+  - `IAuthProvider.prepare()`, `cookies()` and `transportMaterial()` are required for
+    the same reason (needs `@mcp-abap-adt/interfaces` 20.0.0);
+  - `establish()` is the transport's, and the connection delegates to it without
+    asking anything first. The credential contributes a header, cookies and TLS
+    material; earning a CSRF token is the wire's work, because the wire is what
+    holds the session the token is bound to (needs `@mcp-abap-adt/interfaces`
+    21.0.0, where the two credential atoms leave the contract — nothing
+    implemented them);
+  - `skipSessionType` is gone: it described BASIS 7.40, and a deployment is a wire, so
+    it is `LegacyOnPremHttpTransport`;
+  - whether a session exists is `IAdtTransport.sessionEstablished()` — a verdict each
+    wire gives about itself, instead of the connection reading a fingerprint and a flag
+    and deciding for all of them at once.
+
+  A credential you wrote gains three usually-empty members; see
+  [the migration guide](./docs/MIGRATION-6.0.md#writing-your-own-credential).
+
+### Removed
+
+- **The connection no longer answers a `401` for you.** It called `renew()` on the
+  credential, compared the header against the previous one, and rebuilt the session
+  if it had changed — a credential lifetime managed from inside the connection.
+  Renewal on an expiry the provider can SEE still happens, inside
+  `authorizationHeader()`, which is asked per request; the other case — a token the
+  provider still believes in and the server refuses — is a judgement made with what
+  the caller knows, so the refusal surfaces. A refused credential is not a lost
+  session, so the connection stays usable. `TokenAuthProvider` declares
+  `IRenewableCredential` (interfaces 19.0.0), which is what a consumer narrows to
+  before calling `renew()` itself.
+
+- **`disconnect({ deadlineMs })`** takes no arguments, and `SAP_RELEASE_DEADLINE_MS`
+  is gone with it. The parameter bounded a wait for the goodbye to be *answered*,
+  and the method does not act on that answer: it tells the server the session is
+  finished, and whether and when the session is freed is the server's affair. The
+  default was already `0`. Waiting bought a caller nothing while being the one
+  thing that could make a teardown unbounded — the goodbye carries no request
+  timeout by design, so a server that never answered would have held the teardown
+  for the whole deadline. Needs `@mcp-abap-adt/interfaces` 18.0.0, where the
+  parameter leaves the contract. Verified against a live BTP trial before the
+  contract moved: `disconnect()` returned in 1 ms and the goodbye still went out.
+
+- **`SessionStrategy`** and its two implementations. A session mechanism only some
+  wires have, described from inside the class every wire shares and driven by the
+  connection — a second wire abstraction beside `IAdtTransport`. It is the
+  transport's `open()`/`close()` now, which is also what made `connect()` possible
+  over RFC at all.
+
+- **`createAbapConnection()`** and the connection classes it built:
+  `BaseAbapConnection` (`OnPremAbapConnection`), `JwtAbapConnection`
+  (`CloudAbapConnection`), `SamlAbapConnection`, `CertificateAbapConnection`,
+  `KerberosAbapConnection`, `RfcAbapConnection` — 1597 lines. Take a connector,
+  hand it a credential, and hand it a transport — which has no default, because
+  which wire you are on is not something to guess.
+
+- `adaptTransport()`, which dressed a transport in an axios shape so six call
+  sites did not have to be rewritten. They were rewritten.
+
+- `connectionType: 'rfc'` as a way to reach the RFC wire. The wire is an
+  argument now.
+
+  **Kerberos has no direct replacement.** It was single-leg only and untested
+  against a live KDC (#35); a `KerberosAuthProvider` belongs on the credential
+  axis and should be added with a system to test it against.
+
+### Fixed
+
+- Credential cookies are merged into the establishing request rather than
+  overwritten by the wire's own — a SAML session IS that cookie, and replacing
+  it sent the exchange out unauthenticated.
+- The CSRF fallback endpoint is tried only when the primary answers 404. A host
+  that is not answering will not answer a different path, and asking doubled the
+  wait before the real error surfaced.
+- A CSRF token arriving on a refused response (405, or any refusal carrying the
+  header) is kept instead of thrown away by the retry.
+
+## [5.0.0] - 2026-08-21
+
+A connection now says which system it is, closes what it opens, and is handed its
+credential instead of being one. See [Migration to 5.0](./docs/MIGRATION-5.0.md).
+
+### Added
+
+- **`AdtOnPremConnector` and `AdtCloudConnector`.** The class you take states which SYSTEM you
+  are dialling; the auth provider states how you authenticate there. The two are independent, and
+  both were reachable combinations that the old shape got wrong: a communication user against
+  ABAP Cloud, and a bearer token against an on-prem system.
+
+  Nothing is detected. `/sap/bc/adt/core/http/sessions` answers on **on-prem too**, publishing
+  both the session resource and the ICF logoff in one document, and its `DELETE` there leaves the
+  session listed while the logoff removes it — a probe would have chosen the mechanism that
+  releases nothing.
+
+- **Auth providers** — `BasicAuthProvider`, `TokenAuthProvider`, `SamlAuthProvider`,
+  `CertificateAuthProvider` — and `IAuthProvider`, the contract they satisfy. A token provider
+  renews on its own, so nothing is cached here: the header is asked for per request, and on a
+  `401` the provider is told its answer was refused (`refreshToken()`) before being asked again.
+
+- **`createAbapConnection(..., { system })`** builds the connector you name, with a provider from
+  the config. Without it, the old choice by `authType`, warned about once per call.
+
+- **`disconnect({ deadlineMs })`** — the parameter `ISessionLifecycleAware` published and nothing
+  implemented. It bounds the **wait**, never the request: handed to axios it would abort the
+  socket and cancel the release it was waiting for.
+
+### Changed — BREAKING
+
+- **`connect()` fails when the server opened no session**, where it used to warn and hand the
+  connection back. A lock is held by the ABAP session, so a connection without one can read but
+  can hold nothing, and the failure surfaced a request later as `400 Session not found` with the
+  object half-edited. Verified rather than inferred: a connection that received no
+  `SAP_SESSIONID` is listed in the server's session list as nothing at all.
+
+- **`disconnect()` makes a network call**, telling the server the session is finished. It does
+  not wait by default — `SAP_RELEASE_DEADLINE_MS` is `0` — because waiting is for steps whose
+  successor needs the server to have caught up, and a teardown has none. Requests still in flight
+  are running on the session being released and will start failing; that is the caller having
+  asked to disconnect.
+
+- **The five auth connection classes are deprecated** and keep working.
+
+### Removed — BREAKING
+
+- **`reset()`**, from `AbstractAbapConnection` and `RfcAbapConnection`. There is no local-only
+  discard because there is no local-only session: it lives on the server, and dropping the cookie
+  leaves it there. `await disconnect()`, then `connect()` again.
+
+### Fixed
+
+- **Requests stay on the server the session lives on.** A session belongs to one application
+  server, so on a multi-node system a request landing elsewhere gets a different session and any
+  lock held on the first dies — no inactivity, nobody at fault. `sap-adt-saplb` is asked for and
+  sent back, as Eclipse does.
+
+- **A late `401` no longer tears down a healthy session.** The comparison is bound to the session
+  the request went out on, so a refusal answered by a session that has since been replaced is
+  retried rather than acted on.
+
+- **A credential that is cookies reaches the wire.** A SAML provider's cookies are part of the
+  contract and merged with the session jar rather than written over by it — one says who we are,
+  the other which session we are in.
+
+- **A session opened before a failed `connect()` is not abandoned**, and the logoff does not cut
+  a lock chain held open with `beginCriticalSection()`.
+
+### Measured
+
+- 25 connects in a row on-prem: **24-25** given a session with the logoff, **2** without.
+- The server's session list shows the row appear at the second of the call, and go on
+  `disconnect()`; without one it would sit for 30 more minutes.
+- The timeout is **idle-based**: 45 small requests a minute apart held one session straight
+  through a 30-minute window, identity unchanged. There is no keepalive timer here on purpose.
+- Cloud: `AdtCloudConnector` with a token provider — session opened through ADT, three stateful
+  requests holding it, closed by `DELETE` on the address the server published.
+
+### Fixed
+
+- **Every session of a reconnect cycle is released, not only the first.** A release already on
+  its way was treated as "the release still owed" whoever it belonged to, so an in-flight logoff
+  for a previous session suppressed the current one's entirely: `connect → disconnect → connect →
+  disconnect` sent **one** logoff and left the second session open. Not an edge case — the
+  default deadline is `0`, so `disconnect()` does not wait for the logoff and a release is
+  routinely still in flight when the next `connect()` happens, which made this the normal path on
+  any server that does not answer instantly. Releases are now keyed by the session they belong
+  to, and both completion handlers clear by that key, so a late answer about one session cannot
+  discard what is owed for another. Sessions still owed are kept as a set rather than one slot,
+  because more than one can be outstanding and the older was being overwritten.
+
+### Removed — BREAKING
+
+- **`reset()` is gone**, from `AbstractAbapConnection` and `RfcAbapConnection`. There is no
+  local-only discard, because there is no local-only session: the session lives on the server,
+  and dropping the cookie leaves it there. The lifecycle is `connect()` / `disconnect()`,
+  repeatable, and both say what they do to the server.
+
+  It carried nothing `disconnect()` lacks — it cleared the fingerprint at the start of teardown
+  rather than at its end, did not join the transition tail, and returned `void`. That last one
+  is the point: a teardown that reports nothing cannot tell the caller whether the session was
+  released, which is the whole subject of this release.
+
+  No callers outside tests, and it is in neither `IAbapConnection` nor `ISessionLifecycleAware`,
+  so consumers programming against the published contracts are unaffected. `RfcAbapConnection`
+  keeps `close()`, which is its own teardown and always was.
+
+  **Migration:** `conn.reset()` → `await conn.disconnect()`, and `connect()` again to carry on —
+  the connection is reusable. A caller that does not want to wait simply does not `await` it,
+  which is what `reset()` was really used for.
+
+### Fixed
+
+- **`disconnect()` tells the server the session is done, not only the client.** Dropping the cookie
+  left the ABAP session alive until its own timeout — default `http/security_session_timeout`,
+  1800 s — so a process that connects repeatedly left one behind every time. Measured on S/4HANA
+  on-prem: 25 connects in a row with the logoff, 24–25 of them were given a session; without it,
+  2. The server-side view is unambiguous — SM04 showed 25 HTTP sessions for the same user, one per
+  `connect()`, each holding ~12.8 MB, all of them opened by `P=/sap/bc/adt/discovery`, which is the
+  establishing call.
+
+  The logoff says the session is no longer needed; **when the server reclaims it is the
+  server's business** — possibly not until the next `connect()` asks for one — and nothing
+  here waits on that or depends on it. So `disconnect()` **does not wait by default**:
+  waiting is for steps whose successor needs the server to have caught up, and a teardown
+  has no successor. A caller that wants a bounded wait passes it —
+  `disconnect({ deadlineMs })`, the parameter `ISessionLifecycleAware` has published all
+  along and which nothing implemented; the default comes from `SAP_RELEASE_DEADLINE_MS`,
+  which is `0`.
+
+  **The deadline bounds the wait, never the request.** When it expires the waiting stops and
+  the logoff carries on to the server — the contract's word is *detach*. Handed to axios as a
+  request timeout instead, it would abort the socket and cancel the very release it was waiting
+  for: `deadlineMs: 200` against a server answering in 500 ms left the session open, and the
+  default of `0` was more reliable than any small positive value.
+
+  **Each caller waits its own deadline.** Concurrent disconnects join one transition and share
+  its promise, so a wait placed inside it was the first caller's wait imposed on everyone — a
+  caller passing `0` sat through another's 30-second budget, the one guarantee the parameter
+  exists to make. The transition now carries only what must happen once: dispatching the logoff
+  and clearing the local state.
+
+  **A repeat call finishes what is still owed**, as `ISessionLifecycleAware` promises. It could
+  not: `clearSessionState()` drops the cookies, so a second call found nothing to send and the
+  session lived out its 1800 s. The cookies of an incomplete release are kept aside for exactly
+  that retry and dropped as soon as one succeeds; a release already on its way is joined rather
+  than duplicated.
+
+  **The logoff does not cut a lock chain in flight.** It ends the session that chain is running
+  on, so a consumer's `finally` firing on shutdown mid-unlock would leave the object locked and
+  inactive — the damage this release exists to prevent, caused by the release itself.
+  `beginCriticalSection()` is honoured here as it already is for timeouts: the local teardown
+  still happens, the session is recorded as still owed, and calling `disconnect()` again once
+  the chain has finished releases it.
+
+- **A malformed `SAP_RELEASE_DEADLINE_MS` is refused at construction, not at teardown.** It
+  reached `parseInt`, came out `NaN`, and threw from **every** `disconnect()` in the process —
+  blaming a `deadlineMs` argument nobody had passed. It is a startup fault: the same on every
+  call, not the caller's argument, and worth refusing a connection over. `Number()` rather than
+  `parseInt()`, which read `"5s"` as `5` and travelled on as a silently wrong bound.
+
+  And `disconnect()` no longer throws at all, which is what it and the interface both promise.
+  Its place is a `finally` — a connection that was connected must be disconnected — and an
+  exception raised there replaces the error that sent the caller into it. A nonsense per-call
+  `deadlineMs` is reported and the default used instead.
+
+  It surfaces as anything but a session problem: once the server stops issuing sessions it still
+  authenticates every request, so stateless reads and writes keep working and only the
+  lock-bound write fails — `200` for the LOCK, a handle, then `400 Session not found` on the next
+  request and a half-edited object.
+
+  ICF rather than ADT because ADT publishes no session-close: its discovery document lists none on
+  any reachable system — on-prem, cloud, or legacy — and the ADT logon is the discovery call
+  itself. Best effort and never throwing: `disconnect()` must always settle, and a session we
+  could not close beats a teardown that hangs.
+
+  How many sessions a system tolerates is the server's business and is not guessed at here. Using
+  few connections, and reusing them, stays the consumer's decision.
+
+- **A connection the server gave no session now warns.** `sessionFingerprint()` tracks
+  `SAP_SESSIONID*` only, so a server that issued none leaves it empty — and an empty fingerprint
+  can never be classified `replaced`: `observe()` returns `established` or `unchanged` forever,
+  `applyIdentityPolicy()` never fires, `getSessionIdentity()` names nothing. Refusing to connect
+  would be the honest answer and is deliberately not done yet: whether cloud ABAP issues this
+  cookie is unverified, and a rule that wrong would break every cloud consumer to fix an on-prem
+  fault.
+
+### Documentation
+
+- **The guides stop recommending `reset()`**, which this release removes. `USAGE.md` had a
+  runnable `connection.reset()` under *Connection Reset*, `STATEFUL_SESSION_GUIDE.md` offered it
+  as the remedy for CSRF errors, and `MIGRATION-2.0.md` described its teardown — anyone following
+  them got `connection.reset is not a function`. They now say what replaces it and why: starting
+  over means telling the server, and dropping a cookie does not.
+- A doc block left dangling by the same removal had `close()` in `RfcAbapConnection` documented as
+  "Reset the connection … Provides interface compatibility with HTTP connections" — an API that no
+  longer exists.
+
+### Tests
+
+- The stub in `sessionComposition.test.ts` answered every route instantly, `/sap/bc/adt/slow`
+  included, so *does not wait for an in-flight request* held whenever `disconnect()` performed no
+  I/O rather than because the teardown declined to wait. That route now takes 300 ms and the test
+  asserts what its name says.
+- `sessionTeardown.test.ts` covers the teardown contract from the caller's side: the logoff goes
+  out with the session cookies and without a request timeout at any budget; it is detached rather
+  than aborted when a deadline expires; a failing logoff still disconnects; a repeat call re-sends
+  what is owed and sends nothing once it succeeded; two concurrent disconnects share one logoff
+  and keep separate deadlines; a critical section defers it; and a malformed
+  `SAP_RELEASE_DEADLINE_MS` refuses construction.
+
+### Fixed
+
+- **`disconnect()` releases the session this connection holds, and nothing else.** What grew
+  around that sentence — a map of owed sessions, a map of releases in flight, an attempt counter,
+  a give-up rule, a retry across reconnects, and the waiting rules to go with them — is gone. Four
+  review rounds found a defect in each round's own fix, every one of them in that machinery, and
+  none of it was needed: **a connection holds one session**. `connect()` opens it, `disconnect()`
+  closes it, a repeat `connect()` is a NEW session with a new `SAP_SESSIONID`, and an earlier
+  session is not this connection's business — its logoff is already on the wire, or the system
+  times it out.
+
+  Nothing retries, counts, limits or keeps a list. How many connections to run, how frugally, and
+  what to do when a release did not land are the caller's, and were never knowable from inside a
+  single connection.
+
+  The session a release belongs to is now its `SAP_SESSIONID`, not the cookie header it is sent
+  with. The header also carries `sap-XSRF_*`, which rotates within one and the same session, so
+  comparing headers made a session stop recognising itself after a token refresh.
+
+- **A logoff that cannot even be assembled no longer escapes the teardown.** Building it can throw
+  on its own — a certificate connection whose material is not loaded throws while building the
+  agent — and `disconnect()` is documented never to throw and is called from a `finally`, where a
+  throw replaces the error that sent the caller there.
+
+### Documentation
+
+- **The cookies are the session, and a logoff ends it for everyone holding them.** A second
+  connection given the same cookie jar works in the same ABAP session and can use the locks taken
+  in it; `disconnect()` closes that session for all of them, and no connection can see the copies.
+  Written down in `STATEFUL_SESSION_GUIDE.md` and on `disconnect()` itself.
+
+### Changed — BREAKING
+
+- **`connect()` fails when the server opened no session**, instead of warning and handing back a
+  connection whose first lock would be dead on arrival. Locks are held by the ABAP session, so a
+  connection without one can read but can hold nothing; the failure used to surface a request
+  later, as `400 Session not found` with the object half-edited.
+
+  Verified rather than inferred: a connection that received no `SAP_SESSIONID` was held open
+  against an on-prem system and the session list showed **nothing** for it, while one that
+  received the cookie appeared there. No cookie, no session.
+
+  Reported, not decided on. The message says what the server did, what still works, what does
+  not, the usual cause — sessions are limited per user and shared with every other tool logged on
+  as them — and that nothing is retried here, because whether to wait, retry, or release sessions
+  the user still holds depends on what only the caller knows.
+
+  Every transport, not only basic: splitting by authentication type would encode a guess about
+  cloud ABAP, whose ADT endpoint would not answer the bearer obtainable here. If a cloud system
+  turns out to hold sessions without issuing this cookie, this is the rule to revisit.
+
+### Documentation
+
+- **`STATEFUL_SESSION_GUIDE.md` gains "A Lock Lives In The Session".** That a lock dies with the
+  session that took it; that the timeout is an idle one, spent by silence rather than by elapsed
+  time — one small request a minute kept a session alive for 45 minutes past a 30-minute window,
+  identity unchanged; and that any request in the session resets it, which is why this package
+  holds no keepalive timer. Holding a session alive holds a scarce shared slot, and that is the
+  caller's decision to make.
+
 ## [4.0.0] - 2026-08-16
 
 A JWT connection stops answering with an error of its own making. See
@@ -848,7 +1252,9 @@ 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/v4.0.0...HEAD
+[Unreleased]: https://github.com/fr0ster/mcp-abap-connection/compare/v6.0.0...HEAD
+[6.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v5.0.0...v6.0.0
+[5.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v4.0.0...v5.0.0
 [4.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v3.0.0...v4.0.0
 [3.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v2.0.0...v3.0.0
 [2.0.0]: https://github.com/fr0ster/mcp-abap-connection/compare/v1.10.2...v2.0.0