Skip to content

API/server clean-up and fixes (v1.35.0) - #206

Closed
gmpassos wants to merge 6 commits into
masterfrom
refactor/api-server-cleanup
Closed

gmpassos wants to merge 6 commits into
masterfrom
refactor/api-server-cleanup

Conversation

@gmpassos

@gmpassos gmpassos commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

Clean-up of the API/server layer (server, security, root/module, response cache, cron scheduler, mixin, session, utils), plus six bug fixes, each with a test. Entity, condition, SQL and adapter files are not touched (parallel PRs).

Refactors (behavior-preserving)

  • Server: both _processAPIResponse branches end in one _finishResponse (the nested branch still disposes the outer response after building the Response, same order). Renamed: _sendAPIResponse → _buildShelfResponse, _processResponse → _disposeAndCompressResponse, _startImpl2 → _startServersAndInitializeAPIRoot, _errorProcessing → _errorResponse.
  • CORS set once: _resolveAPIResponseHeaders no longer repeats setCORS when !hasCORS. setCORS is deterministic and idempotent (it assigns the same values; Vary is merged without duplicates), so the repeated call changed nothing. The only code between the two calls is body resolution, which doesn't touch CORS headers.
  • Payload reading: _readPayloadBytes and _toUint8List are shared; maxPayloadLength is checked once, before allocating; a single Uint8List block is still not copied.
  • toAPIRequest: _flattenSingleValues builds both headers and query parameters; it uses the local requestedUri; APIServer.sessionIDCookieName is used at all three sites.
  • Header constants: APIServer.headerXAccessToken (security uses its lower-case form, so the exact-match precedence of the alternatives is unchanged), headerServerTiming, headerKeepAlive, headerContentLength, headerXAPIServerWorker, and HttpHeaders.wwwAuthenticateHeader. Lookups stay case-insensitive.
  • Security: one resolveMapped chain in _resolveRequestCredentialsTokens (stays sync when each step is sync). The disposeAuthentication* pairs share _disposeFromTokenStore / _disposeCredentialFromTokenStore. _setRequestCredential is extracted, and the redundant allowLogout && is dropped.
  • Root/module: _resolveModuleOrDefault; APIRoot.apiInfoRoute and APIRoot.defaultAuthenticationRoute replace the literals (incl. apiInfoURL); _routesHandlersPATH → _routesHandlersPATCH.
  • normalizeHeaderValue passes k3 to apiConfig.getPath. Existing callers pass no k3; a test was added.
  • Response cache: an evicted entry is removed once, not once per alternative; requestIfModifiableSince → ifModifiedSince (all private); the 304 store is a void fire-and-forget _storeResponse304; the GET check is done once in cacheResponse.
  • Cron: _execute is split into _runCalls, _storeRunResult and _runLabel. Await order and catch placement are unchanged.
  • Mixin: _findKeyByNormalized is shared by the lower-case and simple-key lookups.
  • Cache fields: renamed *Cache, documented, and declared before their users. Server: _responseCompressionCache (now also used by _createDirectoryHandler), _directoriesStaticHandlersCache. Base: _securityModuleCache, _securityCache/_securityCacheResolved, _hostnameCache, _portCache, _requesterAddressCache, _originCache. Module: _securityCache. Session: _sharedSessionsCache, _sharedMapCacheTimeout. Utils: doc for _toLowerCaseSimpleCache.

Bug fixes (each in its own commit, with a test)

  1. Response cache eviction TypeError: _checkMaxMemorySize sorted _cachedResponses.values, which holds a List<_CachedResponse> for an entry with compressed alternatives, and a List is not Comparable. Entries are now sorted with all their alternatives, by total usage and memory size (_CachedResponse.compareEntries, same order as compareTo). Test: evicting JSON responses that have gzip alternatives.
  2. Expiry memory leak: _expire removed entries without subtracting them from totalMemorySize; it now goes through _remove. Test: the total goes back to 0 after expiry.
  3. Home directory: Directory('~/') is a literal ~ folder, not the home directory. The home is now resolved from HOME/USERPROFILE only, in the new @visibleForTesting APIServerConfig.resolveUserDirectory; the identical macOS/Linux branches are merged. Test included.
  4. JSON-decode error log: catch (e, s) shadowed the payload s, so the log printed the stack trace instead of the payload. Now catch (e, stackTrace). Test: the log record contains the payload.
  5. IdenticalSet grouped elements by hashCode; it now uses identityHashCode. Test: an element whose hashCode changes.
  6. getFieldsKeysInMap passed one caller-provided fieldLC/fieldSimple for every field. They are now computed per field; the parameters are kept (public API) but ignored and @Deprecated. No caller in the package passed them. Test included.

The version is bumped to 1.35.0 (pubspec + BonesAPI.VERSION) because 1.34.0 is already tagged; the CHANGELOG section is started.

Tests run locally

dart format . (clean) and dart analyze --fatal-infos (no issues).

dart test -x docker on: cov_server_http, cov_server_config, bones_api_test, cov_error_zone, cov_security, security_vm, authentication, cov_authentication, cov_root, cov_module, cov_base, cov_server_cache, cron, cron_db_memory, cron_server, cov_pool_weaklist, session, mixin, utils, utils_collection: 469 passed.

The new cache, IdenticalSet and getFieldsKeysInMap tests were also run against the pre-fix sources, where they fail.

🤖 Generated with Claude Code

gmpassos and others added 6 commits November 8, 2026 05:19
- Server: one `_finishResponse` for both `_processAPIResponse` branches;
  helpers renamed to what they do (`_buildShelfResponse`,
  `_disposeAndCompressResponse`, `_startServersAndInitializeAPIRoot`,
  `_errorResponse`); CORS set once; payload reading shared
  (`_readPayloadBytes`, `_toUint8List`, one `maxPayloadLength` check);
  `_flattenSingleValues` for headers and query parameters; header names
  and the session cookie as constants; `normalizeHeaderValue` passes `k3`.
- Security: one `resolveMapped` chain in `_resolveRequestCredentialsTokens`;
  dispose methods share `_disposeFromTokenStore`; `_setRequestCredential`.
- Root/module: `_resolveModuleOrDefault`, `APIRoot.apiInfoRoute` and
  `APIRoot.defaultAuthenticationRoute`; `_routesHandlersPATCH`.
- Response cache: an entry evicted once (not per alternative);
  `ifModifiedSince`; `void` 304 store; one `GET` check.
- Cron: `_execute` split into `_runCalls`, `_storeRunResult`, `_runLabel`.
- Mixin: `_findKeyByNormalized` for the lower-case and simple lookups.
- Cache fields named `*Cache`, documented and declared before their users.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…unting

- `_checkMaxMemorySize` sorted `_cachedResponses.values`, which holds a
  `List<_CachedResponse>` for an entry with compressed alternatives (not
  `Comparable`): a `TypeError` on eviction. It now sorts the entries
  (key + all alternatives), compared by their total usage and memory size
  (`_CachedResponse.compareEntries`, same order as `compareTo`).
- `_expire` removed the entries (200 and its 304) from the map directly,
  so their memory size was never subtracted from `totalMemorySize`: now
  through `_remove`.

Tests: eviction of JSON responses with gzip alternatives; total memory
back to 0 after the cached entries expire.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- `_getUserDirectory` fell back to `Directory('~/')`, a literal `~`
  directory (relative to the current one), not the home directory. The home
  is now resolved only from `HOME`/`USERPROFILE` (Windows first tries
  `USERPROFILE`, the others `HOME`, each with the other as fallback), in
  the new `APIServerConfig.resolveUserDirectory` (`@visibleForTesting`).
  The identical macOS and Linux branches are merged.
- `_resolvePayloadFromString`: `catch (e, s)` shadowed the payload `s`, so
  the JSON-decode error log printed the stack trace in place of the
  payload: now `catch (e, stackTrace)`.

Tests: `resolveUserDirectory` (incl. a literal `~` directory in the
current directory being ignored); the decode error log shows the payload.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
It bucketed elements by `hashCode`: an element whose `hashCode` changed
after being added was looked up in another group, so `contains`, `add`
and `remove` missed it. An identity set now uses `identityHashCode`.

Test: an element with a changing `hashCode`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
It passed the caller's `fieldLC`/`fieldSimple` (the normalized forms of
ONE field) to the lookup of every field, so all the fields after the first
matched that same key. They are now computed per field; the two parameters
are kept (public API) but ignored and `@Deprecated`. The `mapLC` and
`mapSimple` indexes (per map) are still shared by all the fields.
(No caller in the package passed them.)

Test: two fields with `fieldLC`/`fieldSimple` and shared indexes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 8, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.66667% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.84%. Comparing base (32e1dbf) to head (d1f0f33).

Files with missing lines Patch % Lines
lib/src/bones_api_server_cache.dart 88.09% 5 Missing ⚠️
lib/src/bones_api_base.dart 93.75% 1 Missing ⚠️
lib/src/bones_api_server.dart 98.50% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #206      +/-   ##
==========================================
- Coverage   95.85%   95.84%   -0.01%     
==========================================
  Files          75       75              
  Lines       26519    26504      -15     
==========================================
- Hits        25419    25403      -16     
- Misses       1100     1101       +1     
Flag Coverage Δ
unittests 95.84% <96.66%> (-0.01%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@gmpassos

gmpassos commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

Merged into the single v1.35.0 PR: #209.

@gmpassos gmpassos closed this Nov 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant