@mcp-abap-adt/connection 1.10.1 → 2.0.0

package/docs/SCOPE.md

@@ -0,0 +1,44 @@
+# Scope and Boundaries
+
+This package is **one component of the `@mcp-abap-adt/*` family**. Each package owns one concern; together they form an SAP ABAP tooling stack. Keeping the boundaries clear is important — several features that look natural to add here actually belong in sibling packages, and some that look missing (like RFC-to-cloud) do not exist anywhere in the ecosystem because the underlying technology does not support them.
+
+## What this package does
+
+- **HTTP transport to SAP ADT** — request dispatch, CSRF token fetch, cookie and session handling, stateful/stateless session control.
+- **The session lifecycle** — establishing a session and refusing to work without one, tearing it down without cutting in-flight requests, tracking which SAP session it is talking to, and telling the caller when that session is lost while a lock is held. See [USAGE.md — Session Lifecycle](./USAGE.md#session-lifecycle).
+- **RFC transport to on-premise SAP** — via `@mcp-abap-adt/sap-rfc-lite` + NW RFC SDK, calling `SADT_REST_RFC_ENDPOINT` (the same FM Eclipse ADT uses on on-prem).
+- **Applying credentials** handed to it by the caller (Basic user/password, Bearer JWT, SAML session cookies).
+
+## What this package does NOT do, and where it lives instead
+
+| Concern | Belongs in |
+|---|---|
+| Token acquisition (SAML/OAuth2 flows, browser login, PKCE) | `@mcp-abap-adt/auth-broker` |
+| Token validation, refresh, re-authentication, expiry tracking | consumer via `ITokenProvider` (from `@mcp-abap-adt/interfaces`) |
+| Session state persistence across processes | `@mcp-abap-adt/auth-broker` |
+| Auth-type constants, provider error codes, auth lifecycle contracts | `@mcp-abap-adt/interfaces` |
+
+The rule: **if it is about *acquiring* or *refreshing* credentials, it is not our job.** We receive credentials that are valid at call time and use them. The consumer is responsible for handing us fresh ones — they know their IdP, their refresh cadence, their re-auth UX.
+
+## Why there is no RFC to SAP BTP / cloud
+
+Short answer: because SAP does not support it that way, and Eclipse ADT does not do it that way either.
+
+**1. Eclipse ADT talks to cloud over HTTP, not RFC.**
+The `com.sap.adt.communication.http.*` package is the only transport Eclipse ADT uses for ADT itself. Cloud login in Eclipse goes through `SamlWithReentranceTicketLogonFacade` → `IcfEndpointBasedSystemUrlInfoProvider` → `HttpLowLevelConnection.sendRequest`. This is an HTTP flow via the ABAP ICF (Internet Communication Framework) endpoint, with a browser SAML login minting a short-lived reentrance ticket, which is then exchanged for a `MYSAPSSO2` session cookie over HTTP. There is no RFC anywhere in this path. JCo/RFC calls that appear in Eclipse logs come from unrelated features (GUI integration, JCo destination tests) — not ADT.
+
+**2. NW RFC SDK has no JWT or SAML-2.0-XML logon parameter.**
+Inspection of `sapnwrfc.h` and the SDK's reference `sapnwrfc.ini` confirms the supported client logon parameters are: `USER`/`PASSWD`, `X509CERT`, `MYSAPSSO2` (accepts SSO2 tickets and SAP-internal "assertion tickets", *not* SAML 2.0 XML assertions), plus SNC (`SNC_QOP`, `SNC_MYNAME`, `SNC_PARTNERNAME`, `SNC_LIB`) for Kerberos/x509 over RFC. For WebSocket-RFC: `WSHOST`/`WSPORT`, `ALIAS_USER`, `TLS_CLIENT_PSE`, `TLS_CLIENT_CERTIFICATE_LOGON`. No `JWT`, no `BEARER`, no `SAML_ASSERTION`, no `OAUTH` keys exist in the SDK headers.
+
+**3. `@mcp-abap-adt/sap-rfc-lite` is a pure passthrough.**
+It forwards every `(name, value)` pair from the JS `Client(params)` object to `RFC_CONNECTION_PARAMETER[]` without filtering. So the wrapper is not a constraint — the constraint is the SDK itself.
+
+**4. For BTP on-prem scenarios (Cloud Connector), the JWT→x509/SNC swap happens server-side in the CC.** The client-side RFC call still carries classic credentials (x509 + SNC), not the JWT. Supporting that would be adding SNC-over-RFC for on-prem backends behind a CC tunnel — an on-prem extension, not a "cloud RFC" feature.
+
+**Conclusion:** "RFC to cloud" is not a missing feature that would be useful to add; it is a category error. ADT to cloud = HTTP (already supported here). RFC to on-prem = supported here via `connectionType: 'rfc'`. Anything claiming a third combination does not map to what the SAP stack actually exposes.
+
+## See also
+
+- [`INSTALLATION.md`](./INSTALLATION.md)
+- [`USAGE.md`](./USAGE.md)
+- Sibling packages: `@mcp-abap-adt/interfaces`, `@mcp-abap-adt/sap-rfc-lite`, `@mcp-abap-adt/auth-broker`

package/docs/STATEFUL_SESSION_GUIDE.md

@@ -0,0 +1,121 @@
+# Stateful Session Guide (Connection Layer)
+
+> **The header is not what tracks your lock.** `setSessionType('stateful')` sets
+> a per-request header and nothing more — another handler can flip it back while
+> your lock is genuinely open, and a batch never sets it at all. Tell the
+> connection about the lock itself with `beginWindow()` / `endWindow()`: that is
+> what a teardown waits for, what refuses to be abandoned silently, and what
+> makes a replaced session fatal instead of unnoticed. See
+> [USAGE.md — Session Lifecycle](./USAGE.md#session-lifecycle).
+
+
+This document explains how `@mcp-abap-adt/connection` manages HTTP-level session state for SAP ADT requests.
+
+---
+
+## Session Responsibilities
+
+- Fetch and cache CSRF token (per connection instance)
+- Store/reuse SAP cookies (`SAP_SESSIONID`, `sap-usercontext`, etc.)
+- Track WHICH SAP session a connection is in, and refuse to work once it is lost
+
+The connection layer **does not** decide when to lock/unlock objects—that logic lives in the ADT clients. Instead it ensures every request shares the same HTTP session when desired.
+
+---
+
+## Enabling Stateful Sessions
+
+```ts
+import { createAbapConnection } from '@mcp-abap-adt/connection';
+
+const connection = createAbapConnection(config, logger);
+await connection.connect();   // required before any request
+
+// Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
+connection.setSessionType('stateful');
+
+// Now all requests share the same session (cookies, CSRF token)
+await connection.makeAdtRequest({ method: 'GET', url: '/sap/bc/adt/discovery' });
+
+// Switch back to stateless
+connection.setSessionType('stateless');
+```
+
+---
+
+## Knowing Which Session You Are In
+
+```ts
+import { BaseAbapConnection } from '@mcp-abap-adt/connection';
+
+// getSessionIdentity() is on the HTTP connection classes, NOT on the
+// IAbapConnection type that createAbapConnection() returns.
+const connection = new BaseAbapConnection(config, logger);
+await connection.connect();
+
+// Which SAP session this connection is talking to. Changes only when the
+// session itself is replaced — the CSRF cookie is deliberately excluded, since
+// it rotates on a token refresh within one and the same session.
+const identity = connection.getSessionIdentity();   // e.g. 'SAP_SESSIONID_A4H_001=...'
+```
+
+Exporting and importing session state is **not** part of this package: the
+methods that once did it were removed in 0.2.0, and persistence belongs to
+[`@mcp-abap-adt/auth-broker`](https://www.npmjs.com/package/@mcp-abap-adt/auth-broker).
+
+Handing a session to another worker, or resuming one in a CLI tool, therefore
+goes through that package — and whatever it restores, the locks do not come
+back with it: a lock handle from a session this connection did not open is
+dead, and the connection says so rather than letting you use it.
+
+---
+
+## Request Hooks
+
+Every ADT request issued through `makeAdtRequest` automatically:
+
+1. Ensures a CSRF token is available (`HEAD ...` with `x-csrf-token: fetch` if missing).
+2. Adds the cached token + cookies to headers.
+3. Updates stored cookies if SAP returns `set-cookie`.
+4. Retries once when CSRF token is invalid/expired.
+
+This logic is transparent to callers (Builders, handlers, CLI scripts).
+
+---
+
+## Interaction With ADT Clients
+
+- Builders receive the `AbapConnection` instance and optionally a `sessionId`.
+- `@mcp-abap-adt/connection` keeps the HTTP session alive; Builders keep the ADT session consistent.
+- A workflow cannot be resumed by restoring HTTP state into this package: the
+  methods that once did that were removed in 0.2.0. Establish a session with
+  `connect()` and take the locks again — a lock handle from a previous session
+  is dead, and the connection will say so with `ADT_SESSION_REPLACED` rather
+  than let you use it.
+
+---
+
+## Troubleshooting
+
+- **CSRF token errors**: discard the session and establish a new one. `reset()`
+  does that, but it lives on the HTTP connection classes and is **not** on the
+  `IAbapConnection` type `createAbapConnection()` returns — reach it through a
+  concrete type:
+
+  ```ts
+  import { BaseAbapConnection } from '@mcp-abap-adt/connection';
+
+  const connection = new BaseAbapConnection(config, logger);
+  connection.reset();          // queues the cleanup; refuses requests meanwhile
+  await connection.connect();  // a new session, explicitly
+  ```
+- **Session expired**: reauthenticate to obtain a new session.
+- **Multiple connections**: each `createAbapConnection` instance maintains its own cookie jar; share the instance if you need continuity.
+
+---
+
+## Related Docs
+
+- [USAGE.md — Session Lifecycle](./USAGE.md#session-lifecycle) – connect/disconnect, lock windows, a lost session
+- [MIGRATION-2.0.md](./MIGRATION-2.0.md) – what the explicit lifecycle changed for callers
+