@mcp-abap-adt/adt-clients 23.0.0 → 23.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -95,24 +95,26 @@ other request:
95
95
  const cls = client.getClass();
96
96
  const config = { className: 'ZCL_TEST' };
97
97
 
98
- const locked = await cls.lock(config); // stateful from here
98
+ const locked = await cls.lock(config); // the LOCK goes stateful
99
99
  if (!locked.ok) throw new Error(locked.getError().message);
100
100
  const lockHandle = locked.getResult().value;
101
101
 
102
102
  try {
103
103
  await cls.update(config, { source, lockHandle });
104
104
  } finally {
105
- await cls.unlock(config, lockHandle); // stateless again
105
+ await cls.unlock(config, lockHandle); // so does the UNLOCK
106
106
  }
107
107
 
108
108
  await cls.activate(config); // when you want it active
109
109
  ```
110
110
 
111
- `lock` and `unlock` are the only members that change the session type: `lock`
112
- sets `stateful`, `unlock` restores `stateless`. A lock handle is only valid
113
- inside a stateful request on some releases, which is why the unlock has to
114
- happen before anything puts the session back — and why the `finally` above is
115
- the shape to copy.
111
+ `lock` and `unlock` are the only members that change the session type, and
112
+ each only for its own request: the `LOCK` and the `UNLOCK` go out stateful,
113
+ everything between them — the write included — stateless. The `UNLOCK` has to
114
+ reach the ABAP context that holds the lock, which is what the stateful request
115
+ carries it to; a stateless one answers `200` and releases nothing (see
116
+ [STATEFUL_SESSION_GUIDE.md](STATEFUL_SESSION_GUIDE.md)). The `finally` above is
117
+ the shape to copy, because a handle left held refuses the next write.
116
118
 
117
119
  **`lock` answers the handle SAP sent; `unlock` answers SAP's reply.** The handle
118
120
  is read from the `sap-adt-lm-handle` header or from `LOCK_HANDLE` in the body.
@@ -391,11 +393,11 @@ verdict and this library does not look for one in the body either: reading an
391
393
  activation checklist is your `analyse`, written from the responses your own
392
394
  system gives.
393
395
 
394
- Two things worth knowing while you write it. `activationExecuted="false"` has
395
- been observed on an object that was already active, with no message attached —
396
- so the flag on its own does not separate "nothing to do" from "refused". And a
397
- locked object refuses with HTTP 403, which never reaches a body-reading strategy
398
- at all.
396
+ Two things worth knowing while you write it: `activationExecuted="false"` with
397
+ no message means "nothing to do", and a locked object refuses with HTTP 403,
398
+ which never reaches a body-reading strategy at all — see
399
+ [WORKAROUNDS.md](WORKAROUNDS.md#activationexecuted-false-is-not-a-failure).
400
+ `analyseActivation` in `@mcp-abap-adt/adt-strategies` reads both.
399
401
 
400
402
  ## How to check a created object, and when
401
403
 
@@ -524,56 +526,14 @@ all: it is changed and deleted directly.
524
526
 
525
527
  ## What a bare `create()` actually leaves, per type
526
528
 
527
- A POST sometimes builds a minimal working object and sometimes builds nothing.
528
- Which one you get is a property of the type, and it is not guessable — measured
529
- on a cloud system by creating each and asking every way of reading it:
530
-
531
- | Type | What the POST left | A read straight after |
532
- |---|---|---|
533
- | `domain` | a complete object — the create carries the content | 2067 bytes |
534
- | `interface` | a generated skeleton | 53 bytes |
535
- | `class` | a generated skeleton | **refused**, `400`, "wrong input data" |
536
- | `ddl` | an object with no content | `200`, empty |
537
- | `serviceDefinition` | **nothing — the create itself is refused** | — |
538
-
539
- `serviceDefinition` is the clearest case of the second kind: there is nothing to
540
- generate a service from, so the POST answers *"Check of condition failed"* and
541
- no object is made. `program` could not be measured here — an ABAP Cloud system
542
- refuses it outright with `S_DEVELOP`.
543
-
544
- ### The class has a skeleton; you just cannot read it yet
545
-
546
- The class row above is the one to be careful with, because the refusal invites
547
- the wrong conclusion. SAP *did* generate a minimal class. It is stored as the
548
- active version, and it becomes readable the moment the first source is written:
549
-
550
- ```
551
- GET …/source/main?version=active 200 class ZAC_PROBE_INACT definition ← SAP's, lower case
552
- GET …/source/main?version=inactive 200 CLASS zac_probe_inact DEFINITION … ← ours, as written
553
- ```
554
-
555
- Before that first write, every read refuses — `active`, `inactive`, neither,
556
- metadata, source. And nothing else lifts it:
557
-
558
- ```
559
- create ok
560
- read after create refused, wrong input data
561
- read after 30s refused ← not timing
562
- lock ok
563
- read while locked refused
564
- read after unlock refused ← not the lock either
565
- ```
566
-
567
- So the object is not empty and it is not broken. It is unfinished, and the first
568
- `update()` is what finishes it. Activation is a separate matter again: it
569
- promotes what you wrote into the active version, replacing the skeleton.
570
-
571
- **`getVersions()` will not tell you any of this.** It answers `ok` in every state
572
- above — the feed, which `objectVersions` in `@mcp-abap-adt/adt-strategies`
573
- reads — listing version slots rather than content — `99999` for the inactive,
574
- `00000` for the active — so it reports two entries for the class nothing can
575
- read. The count drops to one when activation consumes the inactive slot, which
576
- is real but is not an answer to "is there anything to read".
529
+ A POST sometimes builds a minimal working object and sometimes builds nothing,
530
+ and which one you get is a property of the type: a domain is complete, an
531
+ interface has a generated skeleton, a DDL source answers `200` with an empty
532
+ body, a class has a skeleton that **no read can see until its first source
533
+ write**, and a service definition's create is refused outright.
534
+ `getVersions()` answers `ok` in every one of those states. The measured table,
535
+ the class's read sequence and what to do are in
536
+ [WORKAROUNDS.md](WORKAROUNDS.md#what-a-bare-create-leaves-depends-on-the-type).
577
537
 
578
538
  ## The name is taken from the POST onward, and `validate()` may not say so
579
539
 
@@ -607,18 +567,12 @@ its package.
607
567
 
608
568
  ## Absence does not have one wording
609
569
 
610
- Deleting each object and reading it again produced three different sentences:
611
-
612
- ```
613
- domain Error while importing object ZAC_UNFIN_DOM from the database
614
- interface Resource INTERFACE ZAC_UNFIN_INTF does not exist.
615
- ddl Data definition ZAC_UNFIN_DDLS of version does not exist
616
- ```
617
-
618
- All three are refusals and all three mean the same thing. None of them is worth
619
- matching on: the text is the server's, it is language-dependent, and it varies
620
- by type. If you need to branch on absence, branch on the failure your own
621
- `analyse` decided, not on the sentence.
570
+ Deleting an object and reading it again answers a different sentence per type —
571
+ *"Error while importing object … from the database"* for a domain, *"Resource
572
+ INTERFACE … does not exist."*, *"Data definition … of version does not
573
+ exist"*. All mean the same thing, and none is worth matching on: branch on the
574
+ failure your own `analyse` decided. See
575
+ [WORKAROUNDS.md](WORKAROUNDS.md#what-a-bare-create-leaves-depends-on-the-type).
622
576
 
623
577
  Reproduce with `npx ts-node scripts/probe-inactive-metadata.ts` and
624
578
  `npx ts-node scripts/probe-unfinished-create.ts`.
@@ -183,14 +183,10 @@ Some endpoints via RFC don't support specific Accept content types. The library
183
183
 
184
184
  RFC returns base64 lock handles that may contain spaces, `+`, `=`. All lock handles are encoded with `encodeURIComponent()` when placed in URL query parameters.
185
185
 
186
- ## Known limitation: package update
186
+ ## Packages: one save per ABAP session
187
187
 
188
- `AdtPackage.updateMetadata()` does not work over RFC. Everything else on a package does
189
- — create, lock, unlock, delete — and every other object type updates normally.
190
- The save is refused with `400 ExceptionResourceAlreadyExists`, `PAK/058`, and
191
- the cause sits below the ADT lock, in the package framework's own state rather
192
- than in the lock handle this library sends.
193
-
194
- The evidence and the four endpoint answers that place it are in
195
- [`docs/development/RFC_TESTING.md`](../development/RFC_TESTING.md#known-limitation-package-update).
196
- Use HTTP for package changes on a system that supports it.
188
+ A package can be saved only once per ABAP session: the next update or delete
189
+ from that session is refused with `PAK/058`. Over RFC every call shares one
190
+ session, so an update straight after a create is already refused. The rule for
191
+ both transports and the workaround are in
192
+ [WORKAROUNDS.md](WORKAROUNDS.md#a-package-can-be-saved-only-once-per-abap-session).
@@ -9,10 +9,18 @@ This guide explains how `@mcp-abap-adt/adt-clients` manages ADT sessions for CRU
9
9
  - `lock` returns the `lockHandle`; `update` and `delete` carry it in
10
10
  `options.lockHandle`, and `unlock` gives it back.
11
11
  - **Only `lock` and `unlock` change the session type**, and each covers its own
12
- request and nothing more: `lock` sets stateful, acquires the handle, and puts
13
- the session back to stateless before returning. The window between `lock` and
14
- `unlock` is *not* stateful — the write inside it goes out stateless, carrying
15
- the handle in `options.lockHandle`.
12
+ request and nothing more: `lock` sends its `LOCK` stateful and puts the
13
+ session back to stateless before returning; `unlock` does the same for its
14
+ `UNLOCK`. The window between them is *not* stateful — the write inside it
15
+ goes out stateless, carrying the handle in `options.lockHandle`.
16
+ - **The `UNLOCK` must be stateful.** From `@mcp-abap-adt/connection` 9.3.1 the
17
+ connector sends the context cookie `sap-contextid` with stateful requests
18
+ only. A stateless `UNLOCK` then runs in a fresh ABAP context, answers `200`
19
+ and releases nothing; the next activation or delete is refused with `403`
20
+ EU/510 "currently editing". Every `unlock` in this library sends it stateful
21
+ since 23.0.2 — before that, `AdtInclude`, `AdtService` and `AdtMessageClass`
22
+ did not. A caller with its own `IAbapConnection` needs the same: the cookie
23
+ on the `LOCK` and the `UNLOCK`.
16
24
  - This is Eclipse's model, measured at two scales. A full run against the cloud
17
25
  trial: 803 requests, of which exactly 100 carry `x-sap-adt-sessiontype:
18
26
  stateful` — the 50 `LOCK`s and the 50 `UNLOCK`s, and nothing else. A probe
@@ -45,14 +53,14 @@ const config = { className: 'ZCL_TEST' };
45
53
  // The POST that makes the class shell. Nothing else.
46
54
  await cls.create({ ...config, packageName: 'ZPKG', description: 'Test' });
47
55
 
48
- const locked = await cls.lock(config); // stateful from here
56
+ const locked = await cls.lock(config); // the LOCK goes stateful
49
57
  if (!locked.ok) throw new Error(locked.getError().message);
50
58
  const lockHandle = locked.getResult().value;
51
59
 
52
60
  try {
53
61
  await cls.update(config, { source: updatedCode, lockHandle });
54
62
  } finally {
55
- await cls.unlock(config, lockHandle); // stateless again
63
+ await cls.unlock(config, lockHandle); // so does the UNLOCK
56
64
  }
57
65
 
58
66
  await cls.activate(config);
@@ -84,11 +92,12 @@ middle of one operation would take every other caller down with it. The library
84
92
  goes as far as `setSessionType('stateful' | 'stateless')` and no further.
85
93
 
86
94
  Some ADT operations cannot be done twice in one ABAP session, and this is where
87
- that lands on you rather than on us. The clearest case: a package the session
88
- has just updated **cannot be deleted by that same session** — ADT answers
89
- `PAK/058`, and the same delete from any other session succeeds on the first
90
- attempt, immediately, while the first session is still open. It is ownership of
91
- the framework's state, not a delay: retried for 30 seconds it never succeeds.
95
+ that lands on you rather than on us. The clearest case: a package can be saved
96
+ only once per ABAP session — the next update or delete from that session is
97
+ refused with `PAK/058`, and the same request from any other session succeeds at
98
+ once. It is `CL_PACKAGE`'s session buffer, not a delay: retrying never helps.
99
+ The rule for HTTP and RFC, the evidence and the workaround are in
100
+ [WORKAROUNDS.md](WORKAROUNDS.md#a-package-can-be-saved-only-once-per-abap-session).
92
101
 
93
102
  So when an operation refuses in a way that names editing or locking, and the
94
103
  object is one your session has just changed, the fix is a different session —
@@ -4,6 +4,10 @@ ADT answers are often accurate about the wrong thing. Everything below was
4
4
  observed against a running system, and each entry says what the message looks
5
5
  like, what it actually means, and how to tell the two apart.
6
6
 
7
+ SAP-side behaviour with a consumer-side workaround is collected in
8
+ [WORKAROUNDS.md](WORKAROUNDS.md); the entries below that belong there are short
9
+ and link to it.
10
+
7
11
  ## "You are not authorized to make changes (authorization object S_ABPLNGVS)"
8
12
 
9
13
  Arrives as a `403` with an `<exc:exception>` document, `adtType`
@@ -54,76 +58,30 @@ language version its software component fixes; whether the user holds that value
54
58
  in `ABP_LNG_VS`; and whether they hold the specific `ACTVT` for the operation
55
59
  that failed rather than for the one that succeeded.
56
60
 
57
- **The trap.** It is raised wherever the language version cannot be satisfied —
58
- including cases that have nothing to do with your rights. Creating a class into a
59
- package **that does not exist** answers with this object rather than "package not
60
- found": with no package there is no software component, so there is no language
61
- version to check against, and the refusal surfaces as an authorization failure.
62
-
63
- Before going to PFCG, check that the package in the request exists and that its
64
- software component allows the language version you are writing.
61
+ **The trap.** It is also raised for a create into a package **that does not
62
+ exist** — before going to PFCG, check the package. See
63
+ [WORKAROUNDS.md](WORKAROUNDS.md#s_abplngvs-refuses-a-create-into-a-package-that-does-not-exist).
65
64
 
66
65
  ## A read of an object that is not there returns 200 and an empty body
67
66
 
68
- ADT largely does not refuse a request for a missing object. `source/main` never
69
- answers 404; it answers **200 with zero bytes**. A not-yet-ready read of a
70
- domain, data element, package, table type or function group does the same.
71
-
72
- So "the object is not there" and "the object is there and empty" arrive as the
73
- identical answer, and neither the status nor the body can tell them apart.
74
-
75
- **Why it matters more than it looks.** A read-modify-write that trusts the status
76
- reads nothing, writes nothing back, and erases the object. A listing that treats
77
- the same answer as a failure reports an error for an empty package.
78
-
79
- Neither reading can be the library's, which is why it is a decision you supply:
80
- pass `analyse` in the operation options to say which one applies to your call.
67
+ `source/main` never answers 404, and a not-yet-ready metadata read answers the
68
+ same `200` with zero bytes, so "not there" and "there and empty" are one answer.
69
+ A read-modify-write that trusts the status erases the object. See
70
+ [WORKAROUNDS.md](WORKAROUNDS.md#a-read-answers-200-with-an-empty-body-instead-of-404).
81
71
 
82
72
  ## "Resource ZCL_X: wrong input data for processing" on a read
83
73
 
84
- A `400` with an `<exc:exception>`, `adtType` `ExceptionResourceWrongData`, T100
85
- `SADT_RESOURCE/007`. Note the double space: the object type belongs there and
86
- the server left it out, which is the first sign the message is not about your
87
- request at all.
88
-
89
- It means **a class was created and no source has been written to it yet**. Every
90
- read of one refuses this way — `active`, `inactive`, or neither, metadata or
91
- source. Waiting thirty seconds does not help, and neither does a lock/unlock
92
- cycle. Writing the source does, immediately and without any activation.
93
-
94
- The object is not empty and it is not broken: SAP generated a minimal class and
95
- stored it as the active version, and you can read it back the moment the first
96
- write lands. It is unfinished, not absent.
97
-
98
- Specific to classes. An interface created the same way reads its generated
99
- skeleton at once, a domain is complete on creation, a DDL source answers 200
100
- with an empty body, and a service definition cannot be created bare at all —
101
- its POST is refused with "Check of condition failed".
102
-
103
- The trap is that it reads as "your request is malformed", so the natural
104
- response is to retry, and retrying never works. This library's own suite spent
105
- sixteen seconds a run on eight such retries before anyone measured it, and the
106
- assertion after them had never once executed.
107
-
108
- **What to do:** write the source. A class reads at `version=inactive` while
109
- still under its lock, long before any activation. Do not reach for
110
- `getVersions()` to test readiness — it answers `ok` in this state too, listing
111
- version slots rather than content. See
112
- [OBJECT_LIFECYCLE.md](OBJECT_LIFECYCLE.md#what-a-bare-create-actually-leaves-per-type).
74
+ A `400 ExceptionResourceWrongData`, `SADT_RESOURCE/007`, on every read of a
75
+ class that was created and has no source written yet. It is unfinished, not
76
+ absent or broken: write the source, do not retry. See
77
+ [WORKAROUNDS.md](WORKAROUNDS.md#what-a-bare-create-leaves-depends-on-the-type).
113
78
 
114
79
  ## "Class ZCL_X does not have a TMDIR entry" on an activation
115
80
 
116
- A `200` carrying `<msg type="E" code="OO(045)">`, alongside an informational
117
- `EU(239)` "Errors occurred during generation" — note that the summary of the
118
- errors is severity `I`, so counting by severity finds one error, not two.
119
-
120
- It means **the object does not exist**. The activation went straight to
121
- generation, looked for the class in the method directory, and found nothing.
122
- It does not say "not found", so it reads like a corrupt object; it is an absent
123
- one. The same message serves interfaces, with `Interface` in `T100KEY-V1`.
124
-
125
- Distinguish it from the entry above: `wrong input data` is an object that exists
126
- with nothing in it, `TMDIR` is an object that is not there at all.
81
+ A `200` carrying `<msg type="E" code="OO(045)">`: the object **does not exist**.
82
+ Distinguish it from the entry above — `wrong input data` is an object that
83
+ exists with nothing in it, `TMDIR` is an object that is not there at all. See
84
+ [WORKAROUNDS.md](WORKAROUNDS.md#activationexecuted-false-is-not-a-failure).
127
85
 
128
86
  ## A message class exists; its messages do not
129
87
 
@@ -201,31 +159,15 @@ an object already in this state is SAP GUI territory.
201
159
 
202
160
  ## A refusal can arrive with a 2xx
203
161
 
204
- ADT answers some refusals with **200** carrying an `<exc:exception>` document.
205
- The request reached the server and came back, so nothing throws and every layer
206
- above stores the body as a result.
207
-
208
- Measured on a trial: five of seven probed operations reported no errors
209
- while SAP had refused, three of them writes — a caller believed an object existed
210
- that did not, and that one had been deleted that had not.
211
-
212
- **The status is the channel; the document is the verdict.** There are at least
213
- three refusal shapes and they are not interchangeable:
214
-
215
- | shape | resource |
216
- |---|---|
217
- | `<exc:exception>` | most resources, any status including 200 |
218
- | `<del:message del:type="E">` in `del:checkResponse` | `/deletion/check` |
219
- | `<msg type="E">` in `chkl:messages` | `/activation` |
162
+ The status is the channel; the document is the verdict. ADT has at least three
163
+ refusal shapes, and a `200` can carry any of them. See
164
+ [WORKAROUNDS.md](WORKAROUNDS.md#a-refusal-can-arrive-with-a-2xx-and-an-error-status-names-the-fix).
220
165
 
221
166
  ## Activation reports `activationExecuted="false"` and nothing is wrong
222
167
 
223
- The flag says whether ADT did any work, not whether the work succeeded. An object
224
- that is already active answers `false` with an empty message list — identical, by
225
- the flag alone, to an object that does not exist.
226
-
227
- **Only `<msg type="E">` is the verdict.** An object locked by another session is
228
- a `403` and never reaches this document at all.
168
+ The flag says whether ADT did any work, not whether it succeeded; only
169
+ `<msg type="E">` is the verdict. See
170
+ [WORKAROUNDS.md](WORKAROUNDS.md#activationexecuted-false-is-not-a-failure).
229
171
 
230
172
  ## A deletion check that says "no" is not a failure
231
173
 
@@ -237,12 +179,8 @@ the objects are still on the system, and that is a failure.
237
179
 
238
180
  ## 406 and 415 name the exact content type in their text
239
181
 
240
- The status number says nothing actionable; the sentence names the header:
241
-
242
- - `406` — "Accepted content types: application/vnd.sap.adt.deletion.check.response.v1+xml"
243
- - `415` — "Supported Media Types: …check.request.v1+xml"
244
-
245
- Reading the body is cheaper than guessing content types from a status.
182
+ The status number says nothing actionable; the sentence names the header. See
183
+ [WORKAROUNDS.md](WORKAROUNDS.md#a-refusal-can-arrive-with-a-2xx-and-an-error-status-names-the-fix).
246
184
 
247
185
  ## "No URI-Mapping defined for URI", inside a 200
248
186