From e23175dffa41fe462e60aaeb03ceb8756d958554 Mon Sep 17 00:00:00 2001 From: leotrinh Date: Thu, 5 Mar 2026 19:01:38 +0700 Subject: [PATCH] feat: update version correct cf v3 --- CHANGELOG.md | 65 +++ MIGRATION_GUIDE.md | 38 ++ README.md | 32 +- RELEASE_NOTES.md | 85 +++ doc/Apps.html | 2 +- doc/AppsCopy.html | 2 +- doc/AppsCore.html | 2 +- doc/AppsDeployment.html | 28 +- doc/BuildPacks.html | 2 +- doc/CfIgnoreHelper.html | 2 +- doc/CloudController.html | 2 +- doc/CloudControllerBase.html | 2 +- doc/Domains.html | 4 +- doc/Events.html | 2 +- doc/HttpUtils.html | 17 +- doc/Jobs.html | 516 +++++++++++++++++- doc/Logs.html | 2 +- doc/Organizations.html | 25 +- doc/OrganizationsQuota.html | 2 +- doc/Routes.html | 2 +- doc/ServiceBindings.html | 6 +- doc/ServiceInstances.html | 16 +- doc/ServicePlans.html | 2 +- doc/Services.html | 2 +- doc/Spaces.html | 2 +- doc/SpacesQuota.html | 2 +- doc/Stacks.html | 2 +- doc/UserProvidedServices.html | 2 +- doc/Users.html | 4 +- doc/UsersUAA.html | 2 +- doc/index.html | 2 +- doc/model_cloudcontroller_Apps.js.html | 2 +- doc/model_cloudcontroller_AppsCopy.js.html | 2 +- doc/model_cloudcontroller_AppsCore.js.html | 4 +- ...del_cloudcontroller_AppsDeployment.js.html | 20 +- doc/model_cloudcontroller_BuildPacks.js.html | 4 +- ...el_cloudcontroller_CloudController.js.html | 2 +- ...loudcontroller_CloudControllerBase.js.html | 2 +- doc/model_cloudcontroller_Domains.js.html | 8 +- doc/model_cloudcontroller_Events.js.html | 2 +- doc/model_cloudcontroller_Jobs.js.html | 96 +++- ...odel_cloudcontroller_Organizations.js.html | 50 +- ...cloudcontroller_OrganizationsQuota.js.html | 53 +- doc/model_cloudcontroller_Routes.js.html | 2 +- ...el_cloudcontroller_ServiceBindings.js.html | 8 +- ...l_cloudcontroller_ServiceInstances.js.html | 8 +- ...model_cloudcontroller_ServicePlans.js.html | 2 +- doc/model_cloudcontroller_Services.js.html | 2 +- doc/model_cloudcontroller_Spaces.js.html | 2 +- doc/model_cloudcontroller_SpacesQuota.js.html | 40 +- doc/model_cloudcontroller_Stacks.js.html | 2 +- ...oudcontroller_UserProvidedServices.js.html | 2 +- doc/model_cloudcontroller_Users.js.html | 10 +- doc/model_metrics_Logs.js.html | 2 +- doc/model_uaa_UsersUAA.js.html | 2 +- doc/utils_CfIgnoreHelper.js.html | 2 +- doc/utils_HttpUtils.js.html | 16 +- index.js | 2 +- lib/model/cloudcontroller/AppsCore.js | 2 +- lib/model/cloudcontroller/AppsDeployment.js | 18 +- lib/model/cloudcontroller/BuildPacks.js | 2 +- lib/model/cloudcontroller/Domains.js | 6 +- lib/model/cloudcontroller/Jobs.js | 94 +++- lib/model/cloudcontroller/Organizations.js | 48 +- .../cloudcontroller/OrganizationsQuota.js | 51 +- lib/model/cloudcontroller/ServiceBindings.js | 6 +- lib/model/cloudcontroller/ServiceInstances.js | 6 +- lib/model/cloudcontroller/SpacesQuota.js | 38 +- lib/model/cloudcontroller/Users.js | 8 +- lib/utils/HttpUtils.js | 14 +- package.json | 4 +- plans/reports/audit-v3-api-full-report.md | 236 ++++++++ test/lib/ApiMigrationTests.js | 10 +- test/lib/V3AuditFixMediumLowTests.js | 427 +++++++++++++++ test/lib/V3AuditFixTests.js | 410 ++++++++++++++ 75 files changed, 2326 insertions(+), 275 deletions(-) create mode 100644 plans/reports/audit-v3-api-full-report.md create mode 100644 test/lib/V3AuditFixMediumLowTests.js create mode 100644 test/lib/V3AuditFixTests.js diff --git a/CHANGELOG.md b/CHANGELOG.md index ec6c745..1a83486 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,68 @@ +## Version 1.0.7 2026-03-05 + +**PATCH RELEASE — 7 v3 API Fixes (4 MEDIUM + 3 LOW)** + +Implements all remaining audit findings for v3 API correctness and robustness. Adds support for dual status codes, v3 async job polling, and improves v3/v2 consistency. + +### Bug Fixes — MEDIUM (M1–M4) + +- **M1+L3 — Jobs.js:** Added `getV3Job(jobGuid)` and `pollJob(jobGuid, options)` for v3 async operation polling (`/v3/jobs/:guid`). Clarified distinction between v3 Jobs (async ops) and v3 Tasks (app processes). +- **M2 — AppsDeployment.js:** `removeServiceBindings()` v3 now accepts both 202 (managed async) and 204 (key/UPS sync). +- **M3 — ServiceBindings.js:** `_addV3()` accepts 201 or 202; `_removeV3()` accepts 202 or 204. +- **M4 — ServiceInstances.js:** `_removeV3()` accepts 202 (managed async) or 204 (UPS sync). + +### Bug Fixes — LOW (L1–L3) + +- **L1 — Organizations.js:** Removed ineffective `visibility=private` filter from `_getPrivateDomainsV3()`. +- **L2 — Organizations.js:** All v2/v3 methods now use `getAuthorizationHeader()` consistently. +- **L3 — Jobs.js:** Clarified endpoint mapping and JSDoc for v3 async jobs vs tasks. + +### Enabler +- **HttpUtils.js:** `request()` now accepts `Number|Number[]` for status codes (enables dual-status handling above). + +### Tests +- 27 new unit tests covering all fixes (`test/lib/V3AuditFixMediumLowTests.js`) +- All **139 passing**, 0 failing + +--- + +## Version 1.0.6 2026-03-05 + +**PATCH RELEASE — Fix 9 v3 API Issues (5 CRITICAL + 4 HIGH)** + +Full library audit identified incorrect HTTP status code expectations and wrong v3 request body structures across 8 files. All issues fixed and verified. + +### Bug Fixes — CRITICAL (C1–C5): Runtime Failures + +- **C1 — `AppsCore.remove()` wrong v3 status**: Expected 204 (NO_CONTENT) → Fixed to 202 (ACCEPTED). CF v3 `DELETE /v3/apps/:guid` returns 202 with a job URL for async deletion. +- **C2 — `Domains.remove()` wrong v3 status**: Expected 204 → Fixed to 202. CF v3 `DELETE /v3/domains/:guid` returns 202 Accepted. +- **C3 — `BuildPacks.remove()` wrong v3 status**: Expected 204 → Fixed to 202. CF v3 `DELETE /v3/buildpacks/:guid` returns 202 Accepted. +- **C4 — `Users.remove()` wrong v3 status**: Expected 204 → Fixed to 202. CF v3 `DELETE /v3/users/:guid` returns 202 Accepted. +- **C5 — `HttpUtils.upload()` hardcoded PUT**: v3 package upload (`POST /v3/packages/:guid/upload`) requires POST. Added `options.method` parameter, `AppsDeployment._uploadV3()` now passes `method: "POST"`. v2 path unchanged (defaults to PUT). + +### Bug Fixes — HIGH (H1–H4): API Rejection + +- **H1 — `Domains.add()` wrong v3 body**: Sent flat `organization_guid` field → Fixed to nested `relationships.organization.data.guid` per CF v3 spec. +- **H2 — `Users.add()` wrong v3 body**: Sent `{username, origin}` → Fixed to `{guid}` (UAA user GUID). CF v3 `POST /v3/users` requires the UAA `guid` as the primary identifier. +- **H3 — `OrganizationsQuota._translateToV3()` wrong body structure**: Used flat `limits` object with wrong field names → Fixed to proper nested `apps`, `services`, `routes`, `domains` sub-objects matching CF v3 `organization_quotas` spec. +- **H4 — `SpacesQuota._translateToV3()` wrong body structure**: Same flat `limits` issue → Fixed to nested `apps`, `services`, `routes` sub-objects. Preserves `relationships.organization` on create. + +### Files Modified +- `lib/model/cloudcontroller/AppsCore.js` — C1 +- `lib/model/cloudcontroller/Domains.js` — C2, H1 +- `lib/model/cloudcontroller/BuildPacks.js` — C3 +- `lib/model/cloudcontroller/Users.js` — C4, H2 +- `lib/utils/HttpUtils.js` — C5 +- `lib/model/cloudcontroller/AppsDeployment.js` — C5 +- `lib/model/cloudcontroller/OrganizationsQuota.js` — H3 +- `lib/model/cloudcontroller/SpacesQuota.js` — H4 + +### Tests +- 19 new unit tests covering all 9 fixes (`test/lib/V3AuditFixTests.js`) +- All **112 passing**, 0 failing + +--- + ## Version 1.0.5 2026-03-05 **PATCH RELEASE — Fix 11 Incorrect v3 API Endpoints** diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 542a397..7ae1c6f 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -1,5 +1,43 @@ # Migration Guide: cf-nodejs-client → cf-node-client v1.0.0 +## Important: v1.0.7 — 7 v3 Status Code, Job Polling, Consistency Fixes + +If you are using v1.0.0–v1.0.6 in **v3 mode (default)**, the following methods had wrong HTTP status expectations, missing async job polling, or inconsistent headers: + +**Status code fixes (would reject successful v3 DELETE responses):** +- `AppsDeployment.removeServiceBindings()`, `ServiceBindings._addV3/_removeV3()`, `ServiceInstances._removeV3()` — now correctly accept both 202 and 204 where appropriate + +**Async job polling:** +- `Jobs.getV3Job()` and `Jobs.pollJob()` now available for v3 async operation tracking (`/v3/jobs/:guid`) + +**Consistency fixes:** +- `Organizations._getPrivateDomainsV3()` no longer adds ineffective `visibility=private` filter +- All `Organizations` v2/v3 methods now use `getAuthorizationHeader()` + +**Upgrade to v1.0.7** for correct v3 behavior and async job support. No consumer code changes needed unless you want to use new polling helpers. + +--- + +## Important: v1.0.6 — 9 v3 Status Code & Body Structure Fixes + +If you are using v1.0.0–v1.0.5 in **v3 mode (default)**, the following methods had wrong HTTP status expectations or request body structures: + +**Status code fixes (would reject successful v3 DELETE responses):** +- `AppsCore.remove()`, `Domains.remove()`, `BuildPacks.remove()`, `Users.remove()` — now correctly expect 202 instead of 204 + +**Request body fixes (CF API would reject the request):** +- `Domains.add()` — `organization_guid` now nested in `relationships` structure +- `Users.add()` — now sends `{ guid }` instead of `{ username, origin }` per v3 spec +- `OrganizationsQuota._translateToV3()` — proper nested `apps/services/routes/domains` structure +- `SpacesQuota._translateToV3()` — proper nested `apps/services/routes` structure + +**Upload fix:** +- `HttpUtils.upload()` now accepts `options.method` — v3 package upload uses POST (was hardcoded PUT) + +**Upgrade to v1.0.6** for correct v3 behavior. If you pass v2-style quota options, no caller changes needed. + +> **Breaking**: `Users.add()` in v3 now requires `{ guid: "uaa-user-guid" }` instead of `{ username, origin }`. + ## Important: v1.0.5 — 11 Incorrect v3 Endpoints Fixed If you are using v1.0.0–v1.0.4 in **v3 mode (default)**, the following methods called wrong endpoints: diff --git a/README.md b/README.md index 9f53f66..fbf6d3f 100644 --- a/README.md +++ b/README.md @@ -272,22 +272,22 @@ const orgs = new Organizations("https://api.", { apiVersion: "v2 | Resource | Docs | |----------|------| -| Apps | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/Apps.html) | -| Buildpacks | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/BuildPacks.html) | -| Domains | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/Domains.html) | -| Jobs | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/Jobs.html) | -| Organizations | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/Organizations.html) | -| Organizations Quotas | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/OrganizationsQuota.html) | -| Routes | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/Routes.html) | -| Services | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/Services.html) | -| Service Bindings | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/ServiceBindings.html) | -| Service Instances | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/ServiceInstances.html) | -| Service Plans | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/ServicePlans.html) | -| Spaces | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/Spaces.html) | -| Spaces Quotas | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/SpacesQuota.html) | -| Stacks | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/Stacks.html) | -| User Provided Services | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/UserProvidedServices.html) | -| Users | [API](https://prosociallearneu.github.io/cf-nodejs-client/docs/v0.12.0/Users.html) | +| Apps | [API](https://leotrinh.github.io/cf-node-client/doc/Apps.html) | +| Buildpacks | [API](https://leotrinh.github.io/cf-node-client/doc/BuildPacks.html) | +| Domains | [API](https://leotrinh.github.io/cf-node-client/doc/Domains.html) | +| Jobs | [API](https://leotrinh.github.io/cf-node-client/doc/Jobs.html) | +| Organizations | [API](https://leotrinh.github.io/cf-node-client/doc/Organizations.html) | +| Organizations Quotas | [API](https://leotrinh.github.io/cf-node-client/doc/OrganizationsQuota.html) | +| Routes | [API](https://leotrinh.github.io/cf-node-client/doc/Routes.html) | +| Services | [API](https://leotrinh.github.io/cf-node-client/doc/Services.html) | +| Service Bindings | [API](https://leotrinh.github.io/cf-node-client/doc/ServiceBindings.html) | +| Service Instances | [API](https://leotrinh.github.io/cf-node-client/doc/ServiceInstances.html) | +| Service Plans | [API](https://leotrinh.github.io/cf-node-client/doc/ServicePlans.html) | +| Spaces | [API](https://leotrinh.github.io/cf-node-client/doc/Spaces.html) | +| Spaces Quotas | [API](https://leotrinh.github.io/cf-node-client/doc/SpacesQuota.html) | +| Stacks | [API](https://leotrinh.github.io/cf-node-client/doc/Stacks.html) | +| User Provided Services | [API](https://leotrinh.github.io/cf-node-client/doc/UserProvidedServices.html) | +| Users | [API](https://leotrinh.github.io/cf-node-client/doc/Users.html) | --- diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 8ace189..6fc97dc 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,3 +1,88 @@ +# cf-node-client v1.0.7 — 7 v3 API Fixes (4 MEDIUM + 3 LOW) + +**Package**: cf-node-client v1.0.7 +**Release Date**: March 5, 2026 +**Status**: Production Ready +**Severity**: **Medium/Low — v3 Status Code, Job Polling, Consistency** + +## What's Fixed in v1.0.7 + +Implements all remaining audit findings for v3 API correctness and robustness. Adds support for dual status codes, v3 async job polling, and improves v3/v2 consistency. + +### MEDIUM — Dual Status Codes, Job Polling + +| ID | File | Method | Before | After | +|----|------|--------|--------|-------| +| M1+L3 | Jobs.js | v3 async jobs | No polling for /v3/jobs/:guid | Added getV3Job(), pollJob() | +| M2 | AppsDeployment.js | removeServiceBindings() | expects 204 | expects **202 or 204** | +| M3 | ServiceBindings.js | _addV3/_removeV3 | expects 201/202 only | expects **201 or 202** (add), **202 or 204** (remove) | +| M4 | ServiceInstances.js | _removeV3 | expects 202 only | expects **202 or 204** | + +### LOW — Consistency & Docs + +| ID | File | Issue | Fix | +|----|------|-------|-----| +| L1 | Organizations.js | v3 private domains filter | Removed ineffective visibility=private | +| L2 | Organizations.js | inconsistent auth header | All v2/v3 methods use getAuthorizationHeader() | +| L3 | Jobs.js | endpoint map/docs | Clarified v3 jobs vs tasks | + +### Enabler +- **HttpUtils.js:** `request()` now accepts `Number|Number[]` for status codes (enables dual-status handling above). + +### Tests +- 27 new unit tests in `test/lib/V3AuditFixMediumLowTests.js` +- All **139 tests passing**, 0 failing + +--- + +# cf-node-client v1.0.6 — Fix 9 v3 API Issues (5 CRITICAL + 4 HIGH) + +**Package**: cf-node-client v1.0.6 +**Release Date**: March 5, 2026 +**Status**: Production Ready +**Severity**: **Critical — v3 Status Code & Request Body Corrections** + +## What's Fixed in v1.0.6 + +Full library audit against the [CF API v3 specification](https://v3-apidocs.cloudfoundry.org/) found 9 issues causing runtime failures or API rejections when using v3 mode. All fixed. + +### CRITICAL — Wrong HTTP Status Expectations (C1–C4) + +CF v3 DELETE operations return `202 Accepted` (with async job URL), not `204 No Content`. The library was rejecting successful deletions. + +| ID | File | Method | Before | After | +|----|------|--------|--------|-------| +| C1 | AppsCore.js | `remove()` | expects 204 | expects **202** | +| C2 | Domains.js | `remove()` | expects 204 | expects **202** | +| C3 | BuildPacks.js | `remove()` | expects 204 | expects **202** | +| C4 | Users.js | `remove()` | expects 204 | expects **202** | + +### CRITICAL — Upload Method Mismatch (C5) + +| ID | File | Issue | Fix | +|----|------|-------|-----| +| C5 | HttpUtils.js | `upload()` hardcoded `PUT` | Now accepts `options.method` (default: PUT). AppsDeployment v3 passes `POST` for `/v3/packages/:guid/upload`. | + +### HIGH — Wrong v3 Request Body Structure (H1–H4) + +| ID | File | Method | Before (broken) | After (correct) | +|----|------|--------|-----------------|-----------------| +| H1 | Domains.js | `add()` | `{ organization_guid: "..." }` | `{ relationships: { organization: { data: { guid: "..." } } } }` | +| H2 | Users.js | `add()` | `{ username, origin }` | `{ guid: "uaa-user-guid" }` | +| H3 | OrganizationsQuota.js | `_translateToV3()` | flat `limits` object | nested `apps`, `services`, `routes`, `domains` sub-objects | +| H4 | SpacesQuota.js | `_translateToV3()` | flat `limits` object | nested `apps`, `services`, `routes` sub-objects | + +### Breaking Changes + +- **`Users.add()` v3 body**: Now requires `{ guid: "uaa-user-guid" }` instead of `{ username, origin }`. This matches the CF v3 spec. If you were passing `{ guid: "..." }`, it works as before. If you relied on `username` / `origin` fields being sent to v3, update your caller code. +- **`OrganizationsQuota` / `SpacesQuota` v3 body**: The `_translateToV3()` internal method now produces the correct nested structure. If you were passing v2-style options (`memory_limit`, `total_services`, etc.), the translation is now correct — no caller changes needed. + +### Tests +- 19 new unit tests in `test/lib/V3AuditFixTests.js` +- All **112 tests passing**, 0 failing + +--- + # cf-node-client v1.0.5 — Fix 11 Incorrect v3 API Endpoints **Package**: cf-node-client v1.0.5 diff --git a/doc/Apps.html b/doc/Apps.html index e2e9236..cc618ec 100644 --- a/doc/Apps.html +++ b/doc/Apps.html @@ -184,7 +184,7 @@

Home

Classes