diff --git a/CHANGELOG.md b/CHANGELOG.md index b9a562f9..f437c9d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,51 @@ +## 1.35.0 + +API/server layer clean-up (behavior-preserving): + +- `APIServerWorker`: both branches of `_processAPIResponse` end in one + `_finishResponse`; helpers renamed to what they do (`_buildShelfResponse`, + `_disposeAndCompressResponse`, `_startServersAndInitializeAPIRoot`, + `_errorResponse`). The `CORS` headers are set once (they were set again + when building the headers). +- Request payload: one `_readPayloadBytes` for text and binary payloads, one + `maxPayloadLength` check (no copy of a single `Uint8List` block). +- `APIServer.toAPIRequest`: headers and query parameters flattened by one + helper. New constants: `APIServer.sessionIDCookieName` (`SESSIONID`), + `headerServerTiming`, `headerKeepAlive`, `headerContentLength`, + `headerXAPIServerWorker`; `APIRoot.apiInfoRoute` (`API-INFO`) and + `APIRoot.defaultAuthenticationRoute` (`authenticate`). +- `APIServerConfig.normalizeHeaderValue`: the `k3` path key is used (it was + ignored). +- `APISecurity`: one `resolveMapped` chain resolving a token's credential; + the `disposeAuthentication*` methods share one helper. +- `APIRoot`: the default-module fallback shared by `acceptsRequest` and the + call. +- `APIServerResponseCache`: an evicted entry is removed once (not per + alternative); one `GET` check in `cacheResponse`. +- `APICronScheduler._execute` split (`_runCalls`, `_storeRunResult`). +- `FieldsFromMap`: one lookup helper for the lower-case and simple keys. +- Private cache fields named `*Cache`, documented, declared before their + users. + +Fixes: + +- `APIServerResponseCache`: the eviction (`maxMemorySize` reached) sorted + the cached values, which hold a `List` for an entry with compressed + alternatives: a `TypeError`. The entries are now sorted with all their + alternatives (by total usage and memory size). +- `APIServerResponseCache`: an expired entry (file modified) was removed + without subtracting its memory size from `totalMemorySize`. +- `APIServerConfig`: the user directory (Let's Encrypt paths) fell back to + `Directory('~/')`, a literal `~` directory, not the home: it's resolved + from `HOME`/`USERPROFILE` only (`resolveUserDirectory`). +- `APIServer`: the JSON-decode error log printed the stack trace in place + of the invalid payload (a shadowed `catch` variable). +- `IdenticalSet`: grouped elements by `hashCode`, missing an element whose + `hashCode` changed: now by `identityHashCode`. +- `FieldsFromMap.getFieldsKeysInMap`: the given `fieldLC`/`fieldSimple` + (of one field) were used for every field: now computed per field (the + parameters are ignored and `@Deprecated`). + ## 1.34.0 `null` and `[]` mean the same in a condition: an empty set for `=~`/`!~`, a diff --git a/lib/src/bones_api_base.dart b/lib/src/bones_api_base.dart index 92c6ec26..a8c8a604 100644 --- a/lib/src/bones_api_base.dart +++ b/lib/src/bones_api_base.dart @@ -52,7 +52,7 @@ typedef APILogger = void Function( /// Bones API Library class. class BonesAPI { // ignore: constant_identifier_names - static const String VERSION = '1.34.0'; + static const String VERSION = '1.35.0'; static bool _boot = false; @@ -1033,7 +1033,7 @@ abstract class APIRoot with Initializable, Closable { // first part. var pathPartRoot = apiRequest.pathPartFirst; - if (pathPartRoot == 'API-INFO') { + if (pathPartRoot == apiInfoRoute) { var info = apiInfo(apiRequest); return APIResponse.ok(info as T, mimeType: _mimeTypeJson); } @@ -1068,13 +1068,7 @@ abstract class APIRoot with Initializable, Closable { /// Returns `true` if [apiRequest] is an accepted route/call. bool acceptsRequest(APIRequest apiRequest) { - var module = getModuleByRequest(apiRequest); - if (module == null) { - var def = defaultModuleName; - if (def != null) { - module = _modules![def]; - } - } + var module = _resolveModuleOrDefault(getModuleByRequest(apiRequest)); if (module == null) { if (apiRequest.pathPartAt(0) == authenticationRoute || @@ -1096,12 +1090,7 @@ abstract class APIRoot with Initializable, Closable { APIModule? module, APIRequest request, ) { - if (module == null) { - var def = defaultModuleName; - if (def != null) { - module = _modules![def]; - } - } + module = _resolveModuleOrDefault(module); if (module == null) { return onNoRouteForPath(request); @@ -1110,6 +1099,19 @@ abstract class APIRoot with Initializable, Closable { return module.call(request); } + /// Returns [module] (the module matched by the request path), or the + /// [defaultModuleName] module when no module matched. + /// Shared by [acceptsRequest] and [_callModule], so both resolve a request + /// to the same module. It takes the already matched module (not the + /// request) because `_callImpl` checks the authentication route between + /// matching and this fallback. + APIModule? _resolveModuleOrDefault(APIModule? module) { + if (module != null) return module; + + var def = defaultModuleName; + return def != null ? _modules![def] : null; + } + FutureOr> onNoRouteForPath(APIRequest request) { var posResponse = callHandlers( posApiRequestHandlers, @@ -1126,22 +1128,31 @@ abstract class APIRoot with Initializable, Closable { return _responseNotFoundNoRouteForPath(request); } - String get authenticationRoute => 'authenticate'; + /// The route that returns the [APIRootInfo]/[APIModuleInfo] of an API. + static const String apiInfoRoute = 'API-INFO'; + + /// The default [authenticationRoute] (of [APIRoot] and [APIModule]). + static const String defaultAuthenticationRoute = 'authenticate'; + + String get authenticationRoute => defaultAuthenticationRoute; String? get securityModuleName => null; APIModule? get securityModule => _securityModuleImpl(); - APIModule? _securityModule; + /// Cache of the module named [securityModuleName], resolved by + /// [_securityModuleImpl] (a lookup in the modules map), so that each + /// [securityModule] read doesn't repeat the lookup. + APIModule? _securityModuleCache; APIModule? _securityModuleImpl() { - if (_securityModule != null) return _securityModule; + if (_securityModuleCache != null) return _securityModuleCache; var securityModuleName = this.securityModuleName; if (securityModuleName != null) { var module = getModule(securityModuleName); if (module != null) { - return _securityModule = module; + return _securityModuleCache = module; } else { throw StateError( "Can't find security module with name: $securityModuleName", @@ -1154,15 +1165,20 @@ abstract class APIRoot with Initializable, Closable { APISecurity? get security => _securityImpl(); - APISecurity? _security; - bool _securityResolved = false; + /// Cache of the [APISecurity] of the [securityModule] (possibly `null`), + /// filled by [_securityImpl]: [security] is read on every call. + APISecurity? _securityCache; + + /// Whether [_securityCache] was resolved: needed because `null` is a valid + /// (cached) [security]. + bool _securityCacheResolved = false; APISecurity? _securityImpl() { - if (_securityResolved) return _security; - _securityResolved = true; + if (_securityCacheResolved) return _securityCache; + _securityCacheResolved = true; var securityModule = this.securityModule; - return _security = securityModule?.security; + return _securityCache = securityModule?.security; } @override @@ -2501,9 +2517,11 @@ class APIRequest extends APIMetricSet with APIPayload { } } - String? _hostname; + /// Cache of [hostname], parsed from the `Host` header by [_hostnameImpl] + /// on first read (the headers don't change during the request). + String? _hostnameCache; - String get hostname => _hostname ??= _hostnameImpl(); + String get hostname => _hostnameCache ??= _hostnameImpl(); String _hostnameImpl() { var host = getHeader('host'); @@ -2525,9 +2543,11 @@ class APIRequest extends APIMetricSet with APIPayload { return host; } - int? _port; + /// Cache of [port], parsed from the `Port`/`Host` headers by [_portImpl] + /// on first read. + int? _portCache; - int get port => _port ??= _portImpl(); + int get port => _portCache ??= _portImpl(); int _portImpl() { var port = getHeader('port'); @@ -2553,10 +2573,13 @@ class APIRequest extends APIMetricSet with APIPayload { String get hostnameAndPort => '$hostname:$port'; - String? _requesterAddressResolved; + /// Cache of [requesterAddress], resolved by [_requesterAddressImpl] + /// (the given address, or the `X-Forwarded-For`/`Remote-Address` + /// headers). A `null` result isn't cached (it's re-resolved on each read). + String? _requesterAddressCache; String? get requesterAddress => - _requesterAddressResolved ??= _requesterAddressImpl(); + _requesterAddressCache ??= _requesterAddressImpl(); String? _requesterAddressImpl() { if (_requesterAddress != null) return _requesterAddress; @@ -2579,9 +2602,11 @@ class APIRequest extends APIMetricSet with APIPayload { return null; } - String? _origin; + /// Cache of [origin], resolved by [_originImpl] (the `Origin` header, or + /// built from [scheme] and [hostnameAndPort]) on first read. + String? _originCache; - String get origin => _origin ??= _originImpl(); + String get origin => _originCache ??= _originImpl(); String _originImpl() { var origin = getHeader('origin'); diff --git a/lib/src/bones_api_cron_scheduler.dart b/lib/src/bones_api_cron_scheduler.dart index ccbac8f3..501b4779 100644 --- a/lib/src/bones_api_cron_scheduler.dart +++ b/lib/src/bones_api_cron_scheduler.dart @@ -458,20 +458,90 @@ class APICronScheduler { run.status = APICronRunStatus.running; if (!await store.updateRun(run, previousOwner: previousOwner)) { - _log.warning( - 'Run `${job.name}` (${run.scheduledAt.toIso8601String()}): ' - 'taken by another instance', - ); + _log.warning('${_runLabel(job, run)}: taken by another instance'); return run; } _log.info( - 'Run `${job.name}` (${run.scheduledAt.toIso8601String()}): started, ' + '${_runLabel(job, run)}: started, ' 'owner=$owner${run.calls > 0 ? ', resuming after ${run.calls} call(s)' : ''}', ); renewer.start(); + var (:succeeded, :error, interrupted: interruptedByStore) = await _runCalls( + job, + run, + renewer, + ); + + var interrupted = + interruptedByStore ?? + (renewer.lost ? 'lock lost' : (_stopping ? 'scheduler stopped' : null)); + + if (interrupted != null) { + // Left `running`: resumed by the new owner (or another instance). + _log.warning( + '${_runLabel(job, run)}: ' + '$interrupted, left running after ${run.calls} call(s)', + ); + return run; + } + + var finished = _now; + run.finishedAt = finished; + run.durationMs = finished + .difference(run.startedAt ?? started) + .inMilliseconds; + run.status = succeeded + ? APICronRunStatus.succeeded + : APICronRunStatus.failed; + run.lastError = succeeded ? null : error; + + if (!await _storeRunResult(job, run)) { + // Rejected (taken by another instance) or not stored: as stored. + _log.warning( + '${_runLabel(job, run)}: result ' + '(${run.status.name}) not stored: interrupted', + ); + return run..status = APICronRunStatus.running; + } + + var msg = + '${_runLabel(job, run)}: ' + '${run.status.name}, calls=${run.calls}, attempts=${run.attempts}, ' + 'duration=${run.durationMs}ms'; + + if (succeeded) { + _log.info(msg); + } else { + _log.severe('$msg, error: $error'); + } + + return run; + } + + /// The log label of a [run] of [job]: `` Run `name` (scheduledAt) ``. + /// Used by [_execute] for every message about a run's lifecycle. + static String _runLabel(APICronJob job, APICronJobRun run) => + 'Run `${job.name}` (${run.scheduledAt.toIso8601String()})'; + + /// Calls the route of [job] (with retries) until there's no continuation, + /// storing the progress ([APICronJobRun.calls] and continuation) after + /// each call. Used by [_execute]. + /// + /// Returns whether the run [succeeded], its [error] (when it failed) and, + /// when the progress store was rejected (taken by another instance), why + /// it was [interrupted]. An interruption by the [renewer] (lock lost) or + /// by [stop] only stops the loop: [_execute] checks it afterwards. + /// + /// An error never escapes: it fails the run (a run left `running` by an + /// error would be resumed again and again). + Future<({bool succeeded, String? error, String? interrupted})> _runCalls( + APICronJob job, + APICronJobRun run, + _LockRenewer renewer, + ) async { String? error; var succeeded = false; String? interrupted; @@ -526,58 +596,19 @@ class APICronScheduler { _log.severe('Run `${job.name}`: error', e, s); } - interrupted ??= renewer.lost - ? 'lock lost' - : (_stopping ? 'scheduler stopped' : null); - - if (interrupted != null) { - // Left `running`: resumed by the new owner (or another instance). - _log.warning( - 'Run `${job.name}` (${run.scheduledAt.toIso8601String()}): ' - '$interrupted, left running after ${run.calls} call(s)', - ); - return run; - } - - var finished = _now; - run.finishedAt = finished; - run.durationMs = finished - .difference(run.startedAt ?? started) - .inMilliseconds; - run.status = succeeded - ? APICronRunStatus.succeeded - : APICronRunStatus.failed; - run.lastError = succeeded ? null : error; + return (succeeded: succeeded, error: error, interrupted: interrupted); + } - bool stored; + /// Stores the final result of [run] (already set by [_execute]). Returns + /// `false` if the store rejected it (taken by another instance) or failed + /// (the error is logged, not rethrown). + Future _storeRunResult(APICronJob job, APICronJobRun run) async { try { - stored = await store.updateRun(run); + return await store.updateRun(run); } catch (e, s) { _log.severe('Run `${job.name}`: error storing its result', e, s); - stored = false; - } - - if (!stored) { - // Rejected (taken by another instance) or not stored: as stored. - _log.warning( - 'Run `${job.name}` (${run.scheduledAt.toIso8601String()}): result ' - '(${run.status.name}) not stored: interrupted', - ); - return run..status = APICronRunStatus.running; - } - - var msg = - 'Run `${job.name}` (${run.scheduledAt.toIso8601String()}): ' - '${run.status.name}, calls=${run.calls}, attempts=${run.attempts}, ' - 'duration=${run.durationMs}ms'; - - if (succeeded) { - _log.info(msg); - } else { - _log.severe('$msg, error: $error'); + return false; } - - return run; } /// Calls the route of [job], with the [APICronJob.retry] attempts. diff --git a/lib/src/bones_api_mixin.dart b/lib/src/bones_api_mixin.dart index 6bf4ec45..132a0d9c 100644 --- a/lib/src/bones_api_mixin.dart +++ b/lib/src/bones_api_mixin.dart @@ -705,13 +705,18 @@ mixin FieldsFromMap { return MapEntry(field, value); } - /// Returns a [Map] of [field] keys from [map]. - /// - [field] is case insensitive. + /// Returns a [Map] of [fields] keys from [map]. + /// - The [fields] are case insensitive. + /// - [mapLC] and [mapSimple] (indexes of [map], see [getFieldKeyInMap]) + /// are shared by all the [fields]. + /// - [fieldLC] and [fieldSimple] are ignored: they are the normalized + /// forms of ONE field, computed per field (passing them used the same + /// normalized key for every field). Map getFieldsKeysInMap( List fields, Map map, { - String? fieldLC, - String? fieldSimple, + @Deprecated("Ignored: computed per field") String? fieldLC, + @Deprecated("Ignored: computed per field") String? fieldSimple, Map? mapLC, Map? mapSimple, }) { @@ -719,14 +724,7 @@ mixin FieldsFromMap { .map( (f) => MapEntry( f, - getFieldKeyInMap( - f, - map, - fieldLC: fieldLC, - fieldSimple: fieldSimple, - mapLC: mapLC, - mapSimple: mapSimple, - ), + getFieldKeyInMap(f, map, mapLC: mapLC, mapSimple: mapSimple), ), ) .toMapFromEntries(); @@ -772,47 +770,38 @@ mixin FieldsFromMap { fieldSimple ??= fieldToSimpleKey(field); if (map.containsKey(fieldSimple)) return fieldSimple; - if (mapLC != null) { - if (mapLC.isEmpty) { - for (var e in map.entries) { - var k = e.key; - var kLC = fieldToLCKey(k); - mapLC[kLC] = k; - } - } + return _findKeyByNormalized(map, fieldLC, mapLC, fieldToLCKey) ?? + _findKeyByNormalized(map, fieldSimple, mapSimple, fieldToSimpleKey); + } - var mapKey = mapLC[fieldLC]; - if (mapKey != null) { - return mapKey; - } - } else { - for (var k in map.keys) { - var kLC = fieldToLCKey(k); - if (kLC == fieldLC) { - return k; + /// Returns the key of [map] whose [normalize]d form is [fieldNormalized]. + /// Used by [_getFieldKeyInMapImpl] for the lower-case ([fieldToLCKey]) and + /// the simple ([fieldToSimpleKey]) lookups. + /// + /// If [mapNormalized] (a caller-provided index: normalized key -> [map] + /// key) is given, it's filled on first use (when empty) and used for the + /// lookup, so a caller resolving many fields in the same [map] normalizes + /// its keys only once. On a normalized collision, the index keeps the last + /// key while the scan (without an index) returns the first one. + String? _findKeyByNormalized( + Map map, + String fieldNormalized, + Map? mapNormalized, + String Function(String key) normalize, + ) { + if (mapNormalized != null) { + if (mapNormalized.isEmpty) { + for (var k in map.keys) { + mapNormalized[normalize(k)] = k; } } - } - if (mapSimple != null) { - if (mapSimple.isEmpty) { - for (var e in map.entries) { - var k = e.key; - var kSimple = fieldToSimpleKey(k); - mapSimple[kSimple] = k; - } - } + return mapNormalized[fieldNormalized]; + } - var mapKey = mapSimple[fieldSimple]; - if (mapKey != null) { - return mapKey; - } - } else { - for (var k in map.keys) { - var kSimple = fieldToSimpleKey(k); - if (kSimple == fieldSimple) { - return k; - } + for (var k in map.keys) { + if (normalize(k) == fieldNormalized) { + return k; } } diff --git a/lib/src/bones_api_module.dart b/lib/src/bones_api_module.dart index 725543c1..4a0bf6d1 100644 --- a/lib/src/bones_api_module.dart +++ b/lib/src/bones_api_module.dart @@ -120,7 +120,7 @@ abstract class APIModule with Initializable { final Map _routesHandlersDELETE = {}; - final Map _routesHandlersPATH = + final Map _routesHandlersPATCH = {}; final Map _routesHandlersHEAD = @@ -133,7 +133,7 @@ abstract class APIModule with Initializable { ..._routesHandlersPOST.keys, ..._routesHandlersPUT.keys, ..._routesHandlersDELETE.keys, - ..._routesHandlersPATH.keys, + ..._routesHandlersPATCH.keys, ..._routesHandlersHEAD.keys, }; @@ -158,7 +158,7 @@ abstract class APIModule with Initializable { case APIRequestMethod.DELETE: return _routesHandlersDELETE; case APIRequestMethod.PATCH: - return _routesHandlersPATH; + return _routesHandlersPATCH; case APIRequestMethod.HEAD: return _routesHandlersHEAD; case APIRequestMethod.OPTIONS: @@ -298,7 +298,7 @@ abstract class APIModule with Initializable { APIRequest apiRequest, String routeName, ) { - if (routeName == 'API-INFO') { + if (routeName == APIRoot.apiInfoRoute) { var info = apiInfo(apiRequest); return APIResponse.ok(info as T, mimeType: _mimeTypeJson); } @@ -327,7 +327,7 @@ abstract class APIModule with Initializable { bool acceptsRequest(APIRequest apiRequest) { var routeName = resolveRoute(apiRequest); - if (routeName == 'API-INFO' || routeName == authenticationRoute) { + if (routeName == APIRoot.apiInfoRoute || routeName == authenticationRoute) { return true; } else { var handler = getRouteHandlerByRequest(apiRequest, routeName); @@ -339,18 +339,23 @@ abstract class APIModule with Initializable { APIModuleInfo apiInfo([APIRequest? apiRequest]) => APIModuleInfo(this, apiRequest); - String get authenticationRoute => 'authenticate'; + String get authenticationRoute => APIRoot.defaultAuthenticationRoute; APISecurity? get security => _securityImpl(); - APISecurity? _security; - bool _securityResolved = false; + /// Cache of the [APIRoot.security] (possibly `null`), filled by + /// [_securityImpl]: [security] is read on every [call]. + APISecurity? _securityCache; + + /// Whether [_securityCache] was resolved: needed because `null` is a valid + /// (cached) [security]. + bool _securityCacheResolved = false; APISecurity? _securityImpl() { - if (_securityResolved) return _security; - _securityResolved = true; + if (_securityCacheResolved) return _securityCache; + _securityCacheResolved = true; - return _security = apiRoot.security; + return _securityCache = apiRoot.security; } @override @@ -1109,7 +1114,7 @@ class APIRouteBuilder { ...module._routesHandlers.values, ...module._routesHandlersGET.values, ...module._routesHandlersPOST.values, - ...module._routesHandlersPATH.values, + ...module._routesHandlersPATCH.values, ...module._routesHandlersPUT.values, ...module._routesHandlersDELETE.values, ].toDistinctList(); diff --git a/lib/src/bones_api_security.dart b/lib/src/bones_api_security.dart index 5f73c882..cafe7646 100644 --- a/lib/src/bones_api_security.dart +++ b/lib/src/bones_api_security.dart @@ -522,38 +522,36 @@ abstract class APISecurity { List? previousPermissions, ); - FutureOr disposeAuthenticationPermission(String? token) { - if (token == null) { - return false; - } - - var prevToken = _tokenStore.removeTokenPermissions(token); + FutureOr disposeAuthenticationPermission(String? token) => + _disposeFromTokenStore(token, _tokenStore.removeTokenPermissions); - return prevToken.resolveMapped((prevToken) { - var disposeTokenPermissions = prevToken != null; - return disposeTokenPermissions; - }); - } + FutureOr disposeAuthenticationDataAndPermission(String? token) => + _disposeFromTokenStore(token, _tokenStore.removeTokenDataAndPermissions); - FutureOr disposeAuthenticationDataAndPermission(String? token) { + /// Removes [token]'s entry from the token store with [removeFromStore] and + /// returns whether something was removed (`false` for a `null` [token]). + /// Shared by the `disposeAuthentication*` methods, which only differ in + /// what they remove (token, data, permissions). + FutureOr _disposeFromTokenStore( + String? token, + FutureOr Function(String token) removeFromStore, + ) { if (token == null) { return false; } - var prevToken = _tokenStore.removeTokenDataAndPermissions(token); - - return prevToken.resolveMapped((prevToken) { - var disposeTokenDataAndPermissions = prevToken != null; - return disposeTokenDataAndPermissions; - }); + return removeFromStore(token) + .resolveMapped((prevEntry) => prevEntry != null); } - FutureOr getAuthenticationData( + /// Clears [credential.usernameEntity] and removes its token's entry with + /// [removeFromStore] (see [_disposeFromTokenStore]). Returns whether + /// anything was disposed. Shared by [disposeAuthenticationData] and + /// [disposeAuthenticationToken]. + FutureOr _disposeCredentialFromTokenStore( APICredential credential, - Object? previousData, - ) => null; - - FutureOr disposeAuthenticationData(APICredential credential) { + FutureOr Function(String token) removeFromStore, + ) { var disposeUsernameEntity = credential.usernameEntity != null; credential.usernameEntity = null; @@ -563,31 +561,21 @@ abstract class APISecurity { return disposeUsernameEntity; } - var prevToken = _tokenStore.removeTokenData(token); - - return prevToken.resolveMapped((prevToken) { - var disposeTokenData = prevToken != null; - return disposeUsernameEntity || disposeTokenData; - }); + return _disposeFromTokenStore(token, removeFromStore).resolveMapped( + (disposedFromStore) => disposeUsernameEntity || disposedFromStore, + ); } - FutureOr disposeAuthenticationToken(APICredential credential) { - var disposeUsernameEntity = credential.usernameEntity != null; - credential.usernameEntity = null; - - var token = credential.token; - - if (token == null) { - return disposeUsernameEntity; - } + FutureOr getAuthenticationData( + APICredential credential, + Object? previousData, + ) => null; - var prevToken = _tokenStore.removeToken(token); + FutureOr disposeAuthenticationData(APICredential credential) => + _disposeCredentialFromTokenStore(credential, _tokenStore.removeTokenData); - return prevToken.resolveMapped((prevToken) { - var disposeTokenInfo = prevToken != null; - return disposeUsernameEntity || disposeTokenInfo; - }); - } + FutureOr disposeAuthenticationToken(APICredential credential) => + _disposeCredentialFromTokenStore(credential, _tokenStore.removeToken); FutureOr authenticateByRequest( APIRequest request, { @@ -623,15 +611,13 @@ abstract class APISecurity { false); if (logout) { + // (`logout` implies `allowLogout`.) var allTokens = - allowLogout && - (request.parameters.getAsBool('all') ?? - request.parameters.getAsBool('allTokens', ignoreCase: true) ?? - false); + request.parameters.getAsBool('all') ?? + request.parameters.getAsBool('allTokens', ignoreCase: true) ?? + false; - var credential = credentials.last; - request.credential = credential; - request.originalCredential ??= credential; + var credential = _setRequestCredential(request, credentials.last); return this .logout(credential, allTokens: allTokens, request: request) @@ -646,9 +632,7 @@ abstract class APISecurity { } if (credentials.length == 1) { - var credential = credentials.last; - request.credential = credential; - request.originalCredential ??= credential; + var credential = _setRequestCredential(request, credentials.last); return authenticate(credential, request: request); } @@ -669,6 +653,19 @@ abstract class APISecurity { }); } + /// Sets [credential] as the [request] credential (and as its + /// `originalCredential`, if not set yet). Returns [credential]. + /// Used by [_authenticateByRequestImpl] for the logout and the + /// single-credential paths. + static APICredential _setRequestCredential( + APIRequest request, + APICredential credential, + ) { + request.credential = credential; + request.originalCredential ??= credential; + return credential; + } + void onLogout(APICredential credential) {} FutureOr resumeAuthenticationByRequest( @@ -837,30 +834,22 @@ abstract class APISecurity { String tokenKey, APIToken? validToken, ) { - if (validToken != null) { - var username = validToken.username; - credential = credential.withUsername(username); - return _resolveRequestCredentialsImpl(request, [credential]); - } else { - return getAPIToken(tokenKey).resolveMapped((validToken) { - if (validToken != null) { - var username = validToken.username; - credential = credential.withUsername(username); - return _resolveRequestCredentialsImpl(request, [credential]); - } else { - return validateUnknownToken( - credential.username, - tokenKey, - ).resolveMapped((validToken) { - if (validToken != null) { - var username = validToken.username; - credential = credential.withUsername(username); - } - return _resolveRequestCredentialsImpl(request, [credential]); - }); - } - }); - } + // Resolves the valid token: the given one, else a known token, else + // `validateUnknownToken` (sync when each step is sync): + FutureOr resolvedToken = + validToken ?? + getAPIToken(tokenKey).resolveMapped( + (knownToken) => + knownToken ?? validateUnknownToken(credential.username, tokenKey), + ); + + return resolvedToken.resolveMapped((token) { + // A valid token defines the credential's username: + var tokenCredential = token != null + ? credential.withUsername(token.username) + : credential; + return _resolveRequestCredentialsImpl(request, [tokenCredential]); + }); } FutureOr> _resolveRequestCredentialsImpl( @@ -926,6 +915,13 @@ abstract class APISecurity { .toString(); } + /// The lower-case [APIResponse.headerXAccessToken]: the request headers + /// read from `dart:io` have lower-case names, so it matches in the exact + /// (first) pass of [APIRequest.getHeaderFirstOf], keeping the precedence + /// of the alternatives below. + static final String _headerXAccessTokenLC = APIResponse.headerXAccessToken + .toLowerCase(); + String getRequestParameterToken(APIRequest request) { var token = request.getParameterIgnoreCaseFirstOf( 'token', @@ -936,7 +932,7 @@ abstract class APISecurity { token ??= request.getHeaderFirstOf( 'x-token', 'token', - 'x-access-token', + _headerXAccessTokenLC, 'access-token', ); diff --git a/lib/src/bones_api_server.dart b/lib/src/bones_api_server.dart index e676653f..f1148fe1 100644 --- a/lib/src/bones_api_server.dart +++ b/lib/src/bones_api_server.dart @@ -10,6 +10,7 @@ import 'package:brotli_fast/brotli_fast.dart' show BrotliErrorCode, BrotliException; import 'package:collection/collection.dart'; import 'package:logging/logging.dart' as logging; +import 'package:meta/meta.dart' show visibleForTesting; import 'package:mime/mime.dart'; import 'package:path/path.dart' as pack_path; import 'package:reflection_factory/reflection_factory.dart'; @@ -949,7 +950,7 @@ class APIServerConfig { return header; } else { if (apiConfig != null && k0 != null) { - var val = apiConfig.getPath(k0, k1, k2); + var val = apiConfig.getPath(k0, k1, k2, k3); if (val != null) return val; } return def; @@ -1053,30 +1054,37 @@ class APIServerConfig { return null; } - static Directory? _getUserDirectory() { - var envVars = Platform.environment; + static Directory? _getUserDirectory() => + resolveUserDirectory(Platform.environment, isWindows: Platform.isWindows); - String? home; - if (Platform.isMacOS) { - home = envVars['HOME']; - } else if (Platform.isLinux) { - home = envVars['HOME']; - } else if (Platform.isWindows) { - home = envVars['UserProfile']; - } + /// Resolves the user's home directory from the environment variables + /// [envVars]: `USERPROFILE` on Windows, else `HOME` (each with the other as + /// fallback). Returns `null` if not defined or not an existing directory. + /// + /// The shell's `~` is not used as a fallback: `Directory('~/')` is a + /// literal directory named `~` (relative to the current directory), not + /// the home directory. + @visibleForTesting + static Directory? resolveUserDirectory( + Map envVars, { + required bool isWindows, + }) { + // `Platform.environment` keys are case-insensitive on Windows, but a + // plain `Map` (tests) is not: try both spellings of `USERPROFILE`. + var userProfile = envVars['USERPROFILE'] ?? envVars['UserProfile']; + var home = envVars['HOME']; + + var candidates = isWindows ? [userProfile, home] : [home, userProfile]; + + for (var path in candidates) { + if (path == null || path.trim().isEmpty) continue; - if (home != null) { - var dir = Directory(home); + var dir = Directory(path); if (dir.existsSync()) { return dir.absolute; } } - var dir = Directory('~/'); - if (dir.existsSync()) { - return dir.absolute; - } - return null; } @@ -1665,7 +1673,7 @@ abstract class _APIServerBase extends APIServerConfig { String get url => 'http://$urlHost:$port/'; /// The local `API-INFO` URL of this server. - String get apiInfoURL => 'http://$urlHost:$port/API-INFO'; + String get apiInfoURL => 'http://$urlHost:$port/${APIRoot.apiInfoRoute}'; /// Returns `true` if the basic conditions for Let's Encrypt are configured. /// @@ -1914,12 +1922,7 @@ class APIServer extends _APIServerBase { var method = parseAPIRequestMethod(request.method) ?? APIRequestMethod.GET; - var headers = Map.fromEntries( - request.headersAll.entries.map((e) { - var values = e.value; - return MapEntry(e.key, values.length == 1 ? values[0] : values); - }), - ); + var headers = _flattenSingleValues(request.headersAll); if (cookieless) { headers.remove('cookie'); @@ -1928,14 +1931,9 @@ class APIServer extends _APIServerBase { var requestedUri = request.requestedUri; var path = requestedUri.path; - var parameters = Map.fromEntries( - requestedUri.queryParametersAll.entries.map((e) { - var values = e.value; - return MapEntry(e.key, values.length == 1 ? values[0] : values); - }), - ); + var parameters = _flattenSingleValues(requestedUri.queryParametersAll); - var scheme = request.requestedUri.scheme; + var scheme = requestedUri.scheme; var connectionInfo = _getConnectionInfo(request); var requesterAddress = connectionInfo?.remoteAddress.address; @@ -1952,7 +1950,7 @@ class APIServer extends _APIServerBase { if (useSessionID && !cookieless) { var cookies = _parseCookies(request); if (cookies != null && cookies.isNotEmpty) { - sessionID = cookies['SESSIONID'] ?? cookies['SESSION_ID']; + sessionID = cookies[sessionIDCookieName] ?? cookies['SESSION_ID']; } if (sessionID == null) { @@ -2012,7 +2010,7 @@ class APIServer extends _APIServerBase { newSession: newSession, credential: credential, scheme: scheme, - requestedUri: request.requestedUri, + requestedUri: requestedUri, originalRequest: request, payload: payload, payloadMimeType: mimeType, @@ -2024,6 +2022,19 @@ class APIServer extends _APIServerBase { }); } + /// Flattens a multi-value map (request headers or query parameters): + /// a key with exactly one value maps to that `String`, any other key keeps + /// its `List`. Used by [toAPIRequest], so that the common + /// single-value case is read as a plain `String` by [APIRequest] users. + static Map _flattenSingleValues( + Map> multiValues, + ) => Map.fromEntries( + multiValues.entries.map((e) { + var values = e.value; + return MapEntry(e.key, values.length == 1 ? values[0] : values); + }), + ); + static Map? _parseCookies(Request request) { var headerCookies = request.headersAll['cookie']; if (headerCookies == null || headerCookies.isEmpty) return null; @@ -2144,11 +2155,12 @@ class APIServer extends _APIServerBase { if (s.isEmpty) return null; try { payload = json.decode(s); - } catch (e, s) { + } catch (e, stackTrace) { + // Not `s`: it would shadow the payload `s` logged below. _log.severe( "_resolvePayloadFromString> Error decoding JSON: <<$s>>", e, - s, + stackTrace, ); return null; } @@ -2164,18 +2176,12 @@ class APIServer extends _APIServerBase { Request request, { int? maxPayloadLength, bool? decompressPayload, - }) => request - .read() - .toList() - .then( - (bs) => _loadPayloadBytes( - request, - bs, - maxPayloadLength: maxPayloadLength, - decompressPayload: decompressPayload, - ), - ) - .then((allBytes) { + }) => + _readPayloadBytes( + request, + maxPayloadLength: maxPayloadLength, + decompressPayload: decompressPayload, + ).then((allBytes) { var encoding = mimeType.charsetEncoding ?? utf8; try { @@ -2190,15 +2196,35 @@ class APIServer extends _APIServerBase { Request request, { int? maxPayloadLength, bool? decompressPayload, + }) => _readPayloadBytes( + request, + maxPayloadLength: maxPayloadLength, + decompressPayload: decompressPayload, + ).then((allBytes) => (mimeType, allBytes)); + + /// Reads the whole [request] body and passes its blocks to + /// [_loadPayloadBytes] (size check and optional decompression). + /// Shared by [_loadPayloadString] and [_resolvePayloadBytes], which only + /// differ in how they interpret the resulting bytes. + static Future _readPayloadBytes( + Request request, { + int? maxPayloadLength, + bool? decompressPayload, }) => request.read().toList().then( (bs) => _loadPayloadBytes( request, bs, maxPayloadLength: maxPayloadLength, decompressPayload: decompressPayload, - ).resolveMapped((allBytes) => (mimeType, allBytes)), + ), ); + /// Returns [bytes] itself when it is already a [Uint8List] (no copy), + /// otherwise a [Uint8List] copy of it. Used for the single-block payload + /// in [_loadPayloadBytes] and for the `gzip`/`deflate` decoder outputs. + static Uint8List _toUint8List(List bytes) => + bytes is Uint8List ? bytes : Uint8List.fromList(bytes); + /// The decoded size limit of a Brotli request payload when /// `maxPayloadLength` is not defined (`64 MB`): a few bytes of Brotli /// can decode to GBs (a "decompression bomb"). See [decompressPayload]. @@ -2213,32 +2239,25 @@ class APIServer extends _APIServerBase { maxPayloadLength ??= -1; decompressPayload ??= false; - Uint8List bytes; + var allBytesSz = payloadBlocks.length == 1 + ? payloadBlocks[0].length + : payloadBlocks.map((e) => e.length).sum; - if (payloadBlocks.length == 1) { - final bs0 = payloadBlocks[0]; - if (bs0 is Uint8List) { - bytes = bs0; - } else { - bytes = Uint8List.fromList(bs0); - } + // Checked before copying/concatenating, so an oversized payload is + // rejected without allocating its buffer: + if (maxPayloadLength >= 0 && allBytesSz > maxPayloadLength) { + throw StateError( + "Payload size ($allBytesSz) exceeds `maxPayloadLength` ($maxPayloadLength).", + ); + } - assert(bytes.length == bs0.length); + Uint8List bytes; - if (maxPayloadLength >= 0 && bytes.length > maxPayloadLength) { - throw StateError( - "Payload size (${bytes.length}) exceeds `maxPayloadLength` ($maxPayloadLength).", - ); - } + if (payloadBlocks.length == 1) { + // A single block needs no concatenation (and no copy if it's already + // a `Uint8List`): + bytes = _toUint8List(payloadBlocks[0]); } else { - var allBytesSz = payloadBlocks.map((e) => e.length).sum; - - if (maxPayloadLength >= 0 && allBytesSz > maxPayloadLength) { - throw StateError( - "Payload size ($allBytesSz) exceeds `maxPayloadLength` ($maxPayloadLength).", - ); - } - bytes = Uint8List(allBytesSz); var bytesOffset = 0; @@ -2301,8 +2320,7 @@ class APIServer extends _APIServerBase { } } - var decoded = gzip.decode(bytes); - return decoded is Uint8List ? decoded : Uint8List.fromList(decoded); + return _toUint8List(gzip.decode(bytes)); } /// Decodes in the [compressionIsolatePool] (not blocking the event loop), @@ -2327,8 +2345,7 @@ class APIServer extends _APIServerBase { } static Uint8List _decodePayloadZlib(Uint8List bytes) { - var decoded = zlib.decode(bytes); - return decoded is Uint8List ? decoded : Uint8List.fromList(decoded); + return _toUint8List(zlib.decode(bytes)); } static final RegExp _regExpSpace = RegExp(r'\s+'); @@ -2379,6 +2396,22 @@ class APIServer extends _APIServerBase { static const String headerXAccessTokenExpiration = "X-Access-Token-Expiration"; + /// The cookie that carries the session ID (see [APIRequest.sessionID]). + static const String sessionIDCookieName = 'SESSIONID'; + + /// The `Server-Timing` header (lower-case, as `shelf` normalizes it). + static const String headerServerTiming = 'server-timing'; + + /// The `Keep-Alive` header (lower-case, as `shelf` normalizes it). + static const String headerKeepAlive = 'keep-alive'; + + /// The `Content-Length` header (lower-case, as `shelf` normalizes it). + static const String headerContentLength = 'content-length'; + + /// The header identifying the [APIServerWorker] that answered a request: + /// `workerIndex/totalWorkers`. + static const String headerXAPIServerWorker = 'X-API-Server-Worker'; + /// The header flagging a `cookieless` server. See [headerXCookielessServerValue]. static const String headerXCookielessServer = "X-Cookieless-Server"; @@ -3011,14 +3044,27 @@ final class APIServerWorker extends _APIServerBase { .resolveMapped((response) => _APIResponseStaticFile(response)); } - final Map _directoriesStaticHandlers = {}; + /// Cache of the static-files [Handler] of each root directory (keyed by + /// [Directory.path]), filled by [_getDirectoryStaticHandler]. A handler + /// (and its response cache) is built once per directory and reused, rather + /// than rebuilt (and its cache lost) on each request. + final Map _directoriesStaticHandlersCache = + {}; Handler _getDirectoryStaticHandler(Directory rootDirectory) => - _directoriesStaticHandlers[rootDirectory.path] ??= + _directoriesStaticHandlersCache[rootDirectory.path] ??= _createDirectoryHandler(rootDirectory); APIServerResponseCache? _responseCache; + /// Cache of [responseCompression] (a getter that builds a new + /// [APIResponseCompression] on each read), used by + /// [_createDirectoryHandler] and by [_disposeAndCompressResponse] for every + /// API response. The fields it's built from are `final`, so it's resolved + /// once (lazily, on first use). + late final APIResponseCompression _responseCompressionCache = + responseCompression; + Handler _createDirectoryHandler(Directory rootDirectory) { rootDirectory = Directory(pack_path.normalize(rootDirectory.absolute.path)); @@ -3032,7 +3078,7 @@ final class APIServerWorker extends _APIServerBase { var pipeline = const Pipeline().addMiddleware(aliases.middleware); - var compression = responseCompression; + var compression = _responseCompressionCache; APIResponseCompression Function(Request request, Response response)? resolveCompression; @@ -3372,14 +3418,17 @@ final class APIServerWorker extends _APIServerBase { _log.info("Starting...$_logSectionOpen"); - return _startImpl2().then((ok) { + return _startServersAndInitializeAPIRoot().then((ok) { _log.info("Started: ${ok ? 'OK' : 'Fail'}$_logSectionClose"); return _log.flushMessages().then((_) => ok); }); } - Future _startImpl2() async { + /// Starts the HTTP(S) servers (Let's Encrypt or normal) and hot reload, + /// then initializes the [apiRoot]. Returns whether the [apiRoot] loaded + /// `OK`. Called by [_startImpl], which wraps it with the start log section. + Future _startServersAndInitializeAPIRoot() async { if (isAuxiliaryWorker) { DBAdapter.enableAuxiliaryMode(); } @@ -3395,9 +3444,11 @@ final class APIServerWorker extends _APIServerBase { } if (cookieless) { - _log.info('Cookieless Server: all cookies disabled! (NO `SESSIONID`)'); + _log.info( + 'Cookieless Server: all cookies disabled! (NO `${APIServer.sessionIDCookieName}`)', + ); } else if (useSessionID) { - _log.info('Using `SESSIONID` cookies.'); + _log.info('Using `${APIServer.sessionIDCookieName}` cookies.'); } var workerInfo = totalWorkers > 1 @@ -3587,11 +3638,11 @@ final class APIServerWorker extends _APIServerBase { return _processAPIRequest(request, apiReq); }, onError: (e, s) { - return _errorProcessing(request, apiRequest, e, s); + return _errorResponse(request, apiRequest, e, s); }, ); } catch (e, s) { - return _errorProcessing(request, apiRequest, e, s); + return _errorResponse(request, apiRequest, e, s); } } @@ -3610,7 +3661,7 @@ final class APIServerWorker extends _APIServerBase { return _processCall(request, apiRequest); } } catch (e, s) { - return _errorProcessing(request, apiRequest, e, s); + return _errorResponse(request, apiRequest, e, s); } } @@ -3646,7 +3697,11 @@ final class APIServerWorker extends _APIServerBase { }); } - Response _errorProcessing( + /// Logs an [error] raised while processing [request] and returns a `500` + /// [Response] describing it. Used by [_process] and [_processAPIRequest] + /// for errors thrown outside the route call (errors of the route itself + /// become an [APIResponse.error] in [_processCall]). + Response _errorResponse( Request request, APIRequest? apiRequest, Object error, @@ -3727,6 +3782,11 @@ final class APIServerWorker extends _APIServerBase { APIRequest apiRequest, APIResponse apiResponse, ) { + // The only place the `CORS` headers of an API response are set (the + // headers built later by `_resolveAPIResponseHeaders` are read from this + // `apiResponse`). Use the configured `CORS`, not the [APIResponse] + // defaults, so that a header this server is configured to omit is not + // added. APIServer.setCORS(apiRequest, apiResponse, cors: crossOrigin.api); if (apiResponse is _APIResponseStaticFile) { @@ -3752,52 +3812,72 @@ final class APIServerWorker extends _APIServerBase { return retPayload.resolveMapped((payload) { if (payload is APIResponse) { + // The payload resolved to another `APIResponse` (e.g. an error + // response from a failed payload `Future`): its status and body are + // sent, with the headers of the original `apiResponse`. var apiResponse2 = payload; - return _resolveBody(apiResponse2.payload, apiResponse2).resolveMapped(( - payload2, - ) { - var headers = _resolveAPIResponseHeaders(apiResponse, apiRequest); - - var response = _sendAPIResponse( + return _resolveBody(apiResponse2.payload, apiResponse2).resolveMapped( + (payload2) => _finishResponse( request, apiRequest, apiResponse2, - headers, payload2, - ); - - apiResponse.disposeAsync(); - - return _processResponse(apiRequest, apiResponse2, request, response); - }); - } else { - var headers = _resolveAPIResponseHeaders(apiResponse, apiRequest); - - var response = _sendAPIResponse( - request, - apiRequest, - apiResponse, - headers, - payload, + outerAPIResponse: apiResponse, + ), ); - - return _processResponse(apiRequest, apiResponse, request, response); + } else { + return _finishResponse(request, apiRequest, apiResponse, payload); } }); } + /// Builds the final [Response] of [apiResponse] with the resolved body + /// [payload], then disposes and compresses it. + /// + /// When [apiResponse] came from the payload of another response + /// ([outerAPIResponse]), the headers are taken from [outerAPIResponse], + /// which is disposed after the [Response] is built (it's not passed to + /// [_disposeAndCompressResponse]). Used by [_processAPIResponse] for both + /// cases. + FutureOr _finishResponse( + Request request, + APIRequest apiRequest, + APIResponse apiResponse, + Object? payload, { + APIResponse? outerAPIResponse, + }) { + var headers = _resolveAPIResponseHeaders( + outerAPIResponse ?? apiResponse, + apiRequest, + ); + + var response = _buildShelfResponse( + request, + apiRequest, + apiResponse, + headers, + payload, + ); + + outerAPIResponse?.disposeAsync(); + + return _disposeAndCompressResponse( + apiRequest, + apiResponse, + request, + response, + ); + } + Map _resolveAPIResponseHeaders( APIResponse apiResponse, APIRequest apiRequest, ) { var headers = {}; - if (!apiResponse.hasCORS) { - // Use the configured `CORS`, not the [APIResponse] defaults, so that a - // header this server is configured to omit is not added back here: - APIServer.setCORS(apiRequest, apiResponse, cors: crossOrigin.api); - } + // The `CORS` headers were already set in `apiResponse.headers` by + // `_processAPIResponse` (copied below with the other headers). if (apiResponse.requiresAuthentication) { var type = apiResponse.authenticationType; @@ -3823,7 +3903,8 @@ final class APIServerWorker extends _APIServerBase { headers[HttpHeaders.serverHeader] ??= serverName; if (apiRequest.newSession && !cookieless) { - var setSessionID = 'SESSIONID=${apiRequest.sessionID}'; + var setSessionID = + '${APIServer.sessionIDCookieName}=${apiRequest.sessionID}'; headers.setMultiValue( HttpHeaders.setCookieHeader, setSessionID, @@ -3837,13 +3918,17 @@ final class APIServerWorker extends _APIServerBase { if (authentication.resumed || _needToSendHeaderXAccessToken(apiRequest, headers, tokenKey)) { - headers.setMultiValue('X-Access-Token', tokenKey, ignoreCase: true); + headers.setMultiValue( + APIServer.headerXAccessToken, + tokenKey, + ignoreCase: true, + ); } } headers[HttpHeaders.cacheControlHeader] = apiCacheControl; - headers['X-API-Server-Worker'] = '$workerIndex/$totalWorkers'; + headers[APIServer.headerXAPIServerWorker] = '$workerIndex/$totalWorkers'; // headers['X-APIToken'] = apiRequest.credential?.token ?? '?'; @@ -3851,7 +3936,7 @@ final class APIServerWorker extends _APIServerBase { } /// Resolves the body of an API response, NOT compressed: the API - /// responses are only compressed by [_processResponse] + /// responses are only compressed by [_disposeAndCompressResponse] /// ([compressResponse]), with the headers of the final [Response]. static FutureOr _resolveBody( Object? payload, @@ -3870,7 +3955,10 @@ final class APIServerWorker extends _APIServerBase { compression: APIResponseCompression.none, ); - FutureOr _processResponse( + /// Disposes [apiResponse] and [apiRequest] (their `Response` is already + /// built) and compresses [response], as accepted by [request]. + /// The last step of [_finishResponse]. + FutureOr _disposeAndCompressResponse( APIRequest apiRequest, APIResponse apiResponse, Request request, @@ -3882,14 +3970,12 @@ final class APIServerWorker extends _APIServerBase { return compressResponse( request, response, - compression: _responseCompression, + compression: _responseCompressionCache, addCompressionRatioHeader: true, addServerTiming: true, ); } - late final APIResponseCompression _responseCompression = responseCompression; - bool _needToSendHeaderXAccessToken( APIRequest apiRequest, Map headers, @@ -3904,7 +3990,7 @@ final class APIServerWorker extends _APIServerBase { // Already in the response headers (e.g. set by the route): var headerAccessToken = headers.getMultiValue( - 'x-access-token', + APIServer.headerXAccessToken, ignoreCase: true, ); var notSentByAccessToken = @@ -3916,7 +4002,11 @@ final class APIServerWorker extends _APIServerBase { return needToSendHeaderXAccessToken; } - Response _sendAPIResponse( + /// Builds the `shelf` [Response] of [apiResponse]: records the final + /// metrics (`Server-Timing`), sets the content/cache/keep-alive headers + /// and maps [APIResponse.status] to a status code. It doesn't send + /// anything (`shelf` does, once the handler returns). + Response _buildShelfResponse( Request request, APIRequest apiRequest, APIResponse apiResponse, @@ -3955,16 +4045,16 @@ final class APIServerWorker extends _APIServerBase { var max = apiResponse.keepAliveMaxRequests.clamp(0, 1000000); headers[HttpHeaders.connectionHeader] = 'Keep-Alive'; - headers['keep-alive'] = 'timeout=$timeout, max=$max'; + headers[APIServer.headerKeepAlive] = 'timeout=$timeout, max=$max'; } var allMetrics = apiRequest.hasMetrics ? CombinedMapView([apiRequest.metrics, apiResponse.metrics]) : apiResponse.metrics; - headers['server-timing'] = APIServer.resolveServerTiming( + headers[APIServer.headerServerTiming] = APIServer.resolveServerTiming( allMetrics, - headers['server-timing']?.toString(), + headers[APIServer.headerServerTiming]?.toString(), ); if (cookieless) { @@ -3980,13 +4070,13 @@ final class APIServerWorker extends _APIServerBase { return Response.notFound(payload, headers: headers); case APIResponseStatus.NOT_MODIFIED: { - headers.remove('content-length'); + headers.remove(APIServer.headerContentLength); return Response.notModified(headers: headers); } case APIResponseStatus.UNAUTHORIZED: { var wwwAuthenticate = headers.getAsString( - 'WWW-Authenticate', + HttpHeaders.wwwAuthenticateHeader, ignoreCase: true, ); diff --git a/lib/src/bones_api_server_cache.dart b/lib/src/bones_api_server_cache.dart index 4a2a808e..c9b783a3 100644 --- a/lib/src/bones_api_server_cache.dart +++ b/lib/src/bones_api_server_cache.dart @@ -58,6 +58,9 @@ class APIServerResponseCache { 1024 * 1024 * 1024 * 32, ); + /// The cached entries: each value is a [_CachedResponse] or, once a + /// compressed alternative is added, a `List<_CachedResponse>` (all with + /// the same key). See `asCachedEntries`. final Map<_CachedResponseKey, Object> _cachedResponses = {}; int get cachedResponsesLength => _cachedResponses.length; @@ -191,11 +194,13 @@ class APIServerResponseCache { _log.info( () => "REMOVED $key > File modified: ${prev.file?.path ?? key.path}", ); - _cachedResponses.remove(key); + // Through `_remove`, so the memory size of the removed entries is + // subtracted from the total (it was leaked by a direct map removal): + _remove(key); if (key.statusCode == 200) { var key304 = _CachedResponseKey(304, key.path); - var prev304 = _cachedResponses.remove(key304); + var prev304 = _remove(key304); if (prev304 != null) { _log.info( () => @@ -248,7 +253,9 @@ class APIServerResponseCache { return true; } - void _remove(_CachedResponseKey key) { + /// Removes the entry of [key] (with all its alternatives), subtracting its + /// memory size from the total. Returns the removed value, if any. + Object? _remove(_CachedResponseKey key) { var prev = _cachedResponses.remove(key); if (prev != null) { @@ -260,6 +267,8 @@ class APIServerResponseCache { } } } + + return prev; } bool _checkMaxMemorySize() { @@ -267,26 +276,33 @@ class APIServerResponseCache { var targetMemory = maxMemorySize * 0.80; - var cachedResponses = _cachedResponses.values.toList(); - cachedResponses.sort(); + // Sorted per entry (key), not per value: a value with compressed + // alternatives is a `List<_CachedResponse>`, which isn't `Comparable` + // (sorting the raw values threw a `TypeError`). + var evictionCandidates = _cachedResponses.entries + .map((e) => (key: e.key, cachedEntries: e.value.asCachedEntries!)) + .toList(); + + evictionCandidates.sort( + (a, b) => + _CachedResponse.compareEntries(a.cachedEntries, b.cachedEntries), + ); var totalRemoved = 0; var totalMemoryRemoved = 0; - for (var entry in cachedResponses) { - var cachedEntries = entry.asCachedEntries; + for (var (:key, :cachedEntries) in evictionCandidates) { + for (var cached in cachedEntries) { + ++totalRemoved; + totalMemoryRemoved += cached.memorySize; + } - if (cachedEntries != null) { - for (var cached in cachedEntries) { - ++totalRemoved; - totalMemoryRemoved += cached.memorySize; + // `_remove` drops the whole entry (all its alternatives) and its + // memory size at once. + _remove(key); - _remove(cached.key); - } - - if (_totalCachedResponsesMemorySize <= targetMemory) { - break; - } + if (_totalCachedResponsesMemorySize <= targetMemory) { + break; } } @@ -410,6 +426,9 @@ class APIServerResponseCache { } Future? cacheResponse(Request request, Response response) { + // Only `GET` responses are cached (for any status): + if (request.method != 'GET') return null; + switch (response.statusCode) { case 200: return _cacheResponse200(request, response); @@ -477,22 +496,23 @@ class APIServerResponseCache { return response2; } + /// Stores the `304` [response] (in the background) and returns `null`: + /// a `304` has no body to replace, so the [response] is sent as is. Future? _cacheResponse304(Request request, Response response) { - var method = request.method; - if (method != 'GET') { - return null; - } + var ifModifiedSince = request.ifModifiedSinceHeader; + if (ifModifiedSince == null) return null; - var requestIfModifiableSince = request.ifModifiedSinceHeader; - if (requestIfModifiableSince == null) return null; - - return _cacheResponse304Impl(response, request, requestIfModifiableSince); + _storeResponse304(response, request, ifModifiedSince); + return null; } - Future? _cacheResponse304Impl( + /// Puts a [_CachedResponse304] once the file stat resolves. Fire and + /// forget (`void`): the `304` [response] doesn't depend on it, so it + /// isn't delayed by the file stat. Used by [_cacheResponse304]. + void _storeResponse304( Response response, Request request, - String requestIfModifiableSince, + String ifModifiedSince, ) { var cacheControl = response.headers[HttpHeaders.cacheControlHeader]; var server = response.headers[HttpHeaders.serverHeader]; @@ -506,7 +526,7 @@ class APIServerResponseCache { path: request.url.path, file: file, fileStat: fileStat, - requestIfModifiableSince: requestIfModifiableSince, + ifModifiedSince: ifModifiedSince, cacheControl: cacheControl, server: server, ); @@ -518,16 +538,9 @@ class APIServerResponseCache { _put(cachedResponse); }); - - return null; } Future? _cacheResponse404(Request request, Response response) { - var method = request.method; - if (method != 'GET') { - return null; - } - var path = request.url.path; return _cacheResponse404Impl(path, response); @@ -620,12 +633,12 @@ class _CachedResponseKey { _CachedResponseKey(200, request.url.path); static _CachedResponseKey? status304(Request request) { - var requestIfModifiableSince = request.ifModifiedSinceHeader; - if (requestIfModifiableSince == null) return null; + var ifModifiedSince = request.ifModifiedSinceHeader; + if (ifModifiedSince == null) return null; return _CachedResponseKey304( request.url.path, - requestIfModifiableSince: requestIfModifiableSince, + ifModifiedSince: ifModifiedSince, ); } @@ -647,10 +660,9 @@ class _CachedResponseKey { } class _CachedResponseKey304 extends _CachedResponseKey { - final String? requestIfModifiableSince; + final String? ifModifiedSince; - _CachedResponseKey304(String path, {this.requestIfModifiableSince}) - : super(304, path); + _CachedResponseKey304(String path, {this.ifModifiedSince}) : super(304, path); } abstract class WithMemorySize { @@ -955,18 +967,41 @@ abstract class _CachedResponse bool validate(Request request); @override - int compareTo(_CachedResponse other) { - int cmp; + int compareTo(_CachedResponse other) => _compareUsageAndMemory( + usageCount, + memorySize, + other.usageCount, + other.memorySize, + ); - { - var use1 = usageCount ~/ 1000; - var use2 = other.usageCount ~/ 1000; - cmp = use2.compareTo(use1); - } + /// Compares two cache entries (a response and its compressed + /// alternatives) as [compareTo] compares two responses, using the totals + /// of each entry ([usageCount] and [memorySize] summed): the entry is + /// stored and evicted as a whole. Used to sort the eviction candidates in + /// `APIServerResponseCache._checkMaxMemorySize`. + static int compareEntries( + List<_CachedResponse> entries1, + List<_CachedResponse> entries2, + ) => _compareUsageAndMemory( + entries1.map((e) => e.usageCount).sum, + entries1.map((e) => e.memorySize).sum, + entries2.map((e) => e.usageCount).sum, + entries2.map((e) => e.memorySize).sum, + ); + + /// The order of [compareTo] and [compareEntries]: by usage (in buckets of + /// 1000) then by memory size (in buckets of 8 KB), both descending. + static int _compareUsageAndMemory( + int usage1, + int memory1, + int usage2, + int memory2, + ) { + var cmp = (usage2 ~/ 1000).compareTo(usage1 ~/ 1000); if (cmp == 0) { - var m1 = memorySize ~/ (1024 * 8); - var m2 = other.memorySize ~/ (1024 * 8); + var m1 = memory1 ~/ (1024 * 8); + var m2 = memory2 ~/ (1024 * 8); cmp = m2.compareTo(m1); } @@ -1332,7 +1367,7 @@ class _CachedResponse200 extends _CachedResponseWithBody { path: path, file: file, fileStat: fileStat, - requestIfModifiableSince: lastModified, + ifModifiedSince: lastModified, cacheControl: cacheControl, server: server, ); @@ -1345,7 +1380,7 @@ class _CachedResponse200 extends _CachedResponseWithBody { } class _CachedResponse304 extends _CachedResponse { - final String requestIfModifiableSince; + final String ifModifiedSince; final String? cacheControl; final String? server; @@ -1353,28 +1388,24 @@ class _CachedResponse304 extends _CachedResponse { required super.path, required super.file, super.fileStat, - required this.requestIfModifiableSince, + required this.ifModifiedSince, this.cacheControl, this.server, }) : super(statusCode: 304); @override - _CachedResponseKey _resolveKey() => _CachedResponseKey304( - path, - requestIfModifiableSince: requestIfModifiableSince, - ); + _CachedResponseKey _resolveKey() => + _CachedResponseKey304(path, ifModifiedSince: ifModifiedSince); @override int _computeMemorySize() => - super._computeMemorySize() + (8 + requestIfModifiableSince.memorySize); + super._computeMemorySize() + (8 + ifModifiedSince.memorySize); @override bool validate(Request request) { - var requestIfModifiableSince = request.ifModifiedSinceHeader; + var ifModifiedSince = request.ifModifiedSinceHeader; - var ok = - requestIfModifiableSince != null && - requestIfModifiableSince == this.requestIfModifiableSince; + var ok = ifModifiedSince != null && ifModifiedSince == this.ifModifiedSince; return ok; } @@ -1387,7 +1418,7 @@ class _CachedResponse304 extends _CachedResponse { final server = this.server; var headers = >{ - 'Last-Modified': [requestIfModifiableSince], + 'Last-Modified': [ifModifiedSince], if (cacheControl != null) 'Cache-Control': [cacheControl], if (server != null) 'Server': [server], }; @@ -1400,7 +1431,7 @@ class _CachedResponse304 extends _CachedResponse { @override String toString() => '[304]{ ' - 'If-Modifiable-Since: $requestIfModifiableSince, ' + 'If-Modified-Since: $ifModifiedSince, ' 'memory: ${memorySize.asBestUnit} ' '}' '->$path' diff --git a/lib/src/bones_api_session.dart b/lib/src/bones_api_session.dart index fbc43a93..71291e46 100644 --- a/lib/src/bones_api_session.dart +++ b/lib/src/bones_api_session.dart @@ -137,19 +137,25 @@ class APISessionSet { late final SharedMapField _sharedSessionsField = SharedMapField(sharedSessionsID, sharedStore: sharedStore); - static const Duration _cacheTimeout = Duration(seconds: 1); - - static final Expando> _sharedSessions = + /// The timeout of [SharedMapField.sharedMapCached] while resolving the + /// [SharedMap] of sessions (in [_resolveSharedSessions]). + static const Duration _sharedMapCacheTimeout = Duration(seconds: 1); + + /// Cache of the resolved [SharedMap] of sessions of each [APISessionSet], + /// filled by [_resolveSharedSessions]: resolving it may be asynchronous + /// (shared store), and it's needed by every session operation. + /// An [Expando] so the entry doesn't keep its [APISessionSet] alive. + static final Expando> _sharedSessionsCache = Expando(); FutureOr> _resolveSharedSessions() { - var sharedSessions = _sharedSessions[this]; + var sharedSessions = _sharedSessionsCache[this]; if (sharedSessions != null) return sharedSessions; return _sharedSessionsField - .sharedMapCached(timeout: _cacheTimeout) + .sharedMapCached(timeout: _sharedMapCacheTimeout) .resolveMapped((sharedSessions) { - _sharedSessions[this] = sharedSessions; + _sharedSessionsCache[this] = sharedSessions; return sharedSessions; }); } diff --git a/lib/src/bones_api_utils.dart b/lib/src/bones_api_utils.dart index 9d405400..af55add9 100644 --- a/lib/src/bones_api_utils.dart +++ b/lib/src/bones_api_utils.dart @@ -8,6 +8,10 @@ class StringUtils { static final RegExp _regexpNotLettersAndDigits = RegExp(r'[^a-zA-Z\d]+'); + /// Cache of [toLowerCaseSimple] results (input -> result), filled by + /// [toLowerCaseSimpleCached]: the same (field) names are normalized again + /// and again (e.g. matching entity fields to map keys), and each call runs + /// a [RegExp] replace. Never cleared: meant for a bounded set of names. static final Map _toLowerCaseSimpleCache = {}; /// Cached version of [toLowerCaseSimple]. @@ -431,7 +435,10 @@ class IdenticalSet { : _groups = List.filled(groups.clamp(2, 1000), null); List _getGroup(Object? o) { - var h = o.hashCode; + // `identityHashCode`, not `hashCode`: elements are matched by identity, + // and an element whose `hashCode` changes (a mutable object) would be + // looked up in another group (not found by `contains`/`remove`). + var h = identityHashCode(o); var gIdx = h % _groups.length; var g = _groups[gIdx] ??= []; return g; diff --git a/pubspec.yaml b/pubspec.yaml index 7c369e9e..29c0166b 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,6 +1,6 @@ name: bones_api description: Bones_API - A powerful API backend framework for Dart. It comes with a built-in HTTP Server, route handler, entity handler, SQL translator, and DB adapters. -version: 1.34.0 +version: 1.35.0 homepage: https://github.com/Colossus-Services/bones_api environment: diff --git a/test/bones_api_cov_pool_weaklist_test.dart b/test/bones_api_cov_pool_weaklist_test.dart index f3ae5b40..2a25e812 100644 --- a/test/bones_api_cov_pool_weaklist_test.dart +++ b/test/bones_api_cov_pool_weaklist_test.dart @@ -455,6 +455,27 @@ void main() { f.getFieldsKeysInMap(['id', 'email'], {'ID': 1}), equals({'id': 'ID', 'email': null}), ); + + // The normalized forms are computed per field: a `fieldLC` / + // `fieldSimple` (of one field) is not used for every field. The + // `mapLC`/`mapSimple` indexes are shared: + var mapLC = {}; + var mapSimple = {}; + expect( + f.getFieldsKeysInMap( + ['userId', 'emailAddress'], + {'USERID': 1, 'email_address': 'e'}, + // ignore: deprecated_member_use_from_same_package + fieldLC: 'userid', + // ignore: deprecated_member_use_from_same_package + fieldSimple: 'userid', + mapLC: mapLC, + mapSimple: mapSimple, + ), + equals({'userId': 'USERID', 'emailAddress': 'email_address'}), + ); + expect(mapLC, isNotEmpty); + expect(mapSimple, isNotEmpty); }); }); diff --git a/test/bones_api_cov_server_cache_test.dart b/test/bones_api_cov_server_cache_test.dart index a0908866..031ab532 100644 --- a/test/bones_api_cov_server_cache_test.dart +++ b/test/bones_api_cov_server_cache_test.dart @@ -1014,6 +1014,68 @@ void main() { expect(cache.toString(), contains('fileStatTimeout: 2 d')); }); + test('max memory size cleaning: entries with alternatives', () async { + // Entries with compressed alternatives are stored as a `List`: the + // eviction sorted the raw values and threw a `TypeError` on them. + var cache = APIServerResponseCache( + maxMemorySize: 1024 * 1024, + fileStatTimeout: Duration(days: 2), + ); + + var inner = _FakeStaticHandler(tmpDir); + for (var i = 0; i < 8; ++i) { + var content = List.generate(30000, (j) => 'f$i:${j * 7919}').join(','); + inner.overrides['t$i.json'] = (request) => Response.ok( + utf8.encode('[$content]'), + headers: {'content-type': 'application/json'}, + ); + } + + var handler = cache.middleware(inner.call); + + for (var i = 0; i < 8; ++i) { + var r = await handler(_get('t$i.json')); + expect(r.statusCode, equals(200)); + + // A compressed alternative of the same entry: + var rGz = await handler( + _get('t$i.json', headers: {'accept-encoding': 'gzip'}), + ); + expect(rGz.statusCode, equals(200)); + expect(rGz.headers['content-encoding'], equals('gzip')); + } + + expect(inner.calls, equals(8)); + expect(cache.totalMemorySize, lessThanOrEqualTo(1024 * 1024 * 1.5)); + expect(cache.cachedResponsesLength, lessThan(8)); + }); + + test('expired entries: memory size subtracted', () async { + var file = writeFile('e.txt', 'Hello E'); + + var cache = APIServerResponseCache(fileStatTimeout: Duration.zero); + var inner = _FakeStaticHandler(tmpDir); + var handler = cache.middleware(inner.call); + + var r1 = await handler(_get('e.txt')); + expect(await _readBody(r1), equals('Hello E')); + + // 200 + 304: + expect(cache.cachedResponsesLength, equals(2)); + expect(cache.totalMemorySize, greaterThan(0)); + + file.writeAsStringSync('Hello E - modified!'); + file.setLastModifiedSync(DateTime.now().add(Duration(seconds: 10))); + await Future.delayed(Duration(milliseconds: 5)); + + // A lookup of the modified file expires its 200 and 304 entries + // (without caching anything new): + expect(await cache.getCachedResponse(_get('e.txt')), isNull); + + expect(cache.cachedResponsesLength, equals(0)); + expect(cache.totalMemorySize, equals(0)); + }); + test('multi-value headers + previous server-timing', () async { var cache = APIServerResponseCache(); var inner = _FakeStaticHandler(tmpDir); diff --git a/test/bones_api_cov_server_config_test.dart b/test/bones_api_cov_server_config_test.dart index 49da63f3..f9c0ad36 100644 --- a/test/bones_api_cov_server_config_test.dart +++ b/test/bones_api_cov_server_config_test.dart @@ -6,6 +6,7 @@ import 'dart:typed_data'; import 'package:args_simple/args_simple.dart'; import 'package:bones_api/bones_api_server.dart'; import 'package:bones_api/src/bones_api_server_cache.dart'; +import 'package:logging/logging.dart' as logging; import 'package:path/path.dart' as pack_path; import 'package:shelf/shelf.dart'; import 'package:test/test.dart'; @@ -463,6 +464,27 @@ void main() { ), equals('def'), ); + + // `k3` is part of the config path (it was ignored before): + var apiConfig4 = APIConfig({ + 'cache': { + 'api': { + 'v2': {'cache_control': 'from-config-k3'}, + }, + }, + }); + expect( + APIServerConfig.normalizeHeaderValue( + null, + 'def', + apiConfig4, + 'cache', + 'api', + 'v2', + 'cache_control', + ), + equals('from-config-k3'), + ); }); test('resolveDomainsRoots', () { @@ -517,6 +539,64 @@ void main() { } }); + test('resolveUserDirectory', () { + var home = tmpDir.absolute.path; + var other = pack_path.join(home, 'other'); + Directory(other).createSync(); + + expect( + APIServerConfig.resolveUserDirectory({ + 'HOME': home, + }, isWindows: false)!.path, + equals(home), + ); + expect( + APIServerConfig.resolveUserDirectory({ + 'USERPROFILE': home, + 'HOME': other, + }, isWindows: true)!.path, + equals(home), + ); + expect( + APIServerConfig.resolveUserDirectory({ + 'UserProfile': home, + }, isWindows: true)!.path, + equals(home), + ); + // Fallback to the other variable: + expect( + APIServerConfig.resolveUserDirectory({ + 'USERPROFILE': home, + }, isWindows: false)!.path, + equals(home), + ); + + // Not defined, blank or not existing: `null`. Never a literal `~` + // directory (the shell's `~` is not expanded by `Directory`): + var cwd = Directory.current; + Directory.current = tmpDir; + try { + Directory('~').createSync(); + expect( + APIServerConfig.resolveUserDirectory({}, isWindows: false), + isNull, + ); + } finally { + Directory.current = cwd; + } + + expect( + APIServerConfig.resolveUserDirectory({'HOME': ' '}, isWindows: false), + isNull, + ); + expect( + APIServerConfig.resolveUserDirectory({ + 'HOME': pack_path.join(home, 'nope'), + }, isWindows: false), + isNull, + ); + }); + test('resolve* from APIConfig', () { var apiConfig = APIConfig({ 'server': { @@ -1335,15 +1415,37 @@ void main() { }), ); - var invalid = await toAPIRequest( - Request( - 'POST', - Uri.parse('http://localhost/a'), - headers: {'content-type': 'application/json'}, - body: '{invalid', - ), - ); + // The error log shows the invalid payload (the `catch` variable + // shadowed it, logging the stack trace in its place): + var records = []; + var sub = logging.Logger.root.onRecord.listen((r) { + if (r.message.contains('Error decoding JSON')) records.add(r); + }); + + var prevLevel = logging.Logger.root.level; + logging.Logger.root.level = logging.Level.ALL; + + APIRequest invalid; + try { + invalid = await toAPIRequest( + Request( + 'POST', + Uri.parse('http://localhost/a'), + headers: {'content-type': 'application/json'}, + body: '{invalid', + ), + ); + await Future.delayed(Duration(milliseconds: 10)); + } finally { + logging.Logger.root.level = prevLevel; + await sub.cancel(); + } + expect(invalid.payload, isNull); + expect(records, hasLength(1)); + expect(records.first.message, contains('<<{invalid>>')); + expect(records.first.error, isA()); + expect(records.first.stackTrace, isNotNull); var blank = await toAPIRequest( Request( diff --git a/test/bones_api_utils_collection_test.dart b/test/bones_api_utils_collection_test.dart index 63db1731..6fef0adb 100644 --- a/test/bones_api_utils_collection_test.dart +++ b/test/bones_api_utils_collection_test.dart @@ -5,6 +5,20 @@ import 'package:test/test.dart'; import 'bones_api_test_entities.dart'; +/// An object whose [hashCode] can change (a mutable key). +class _MutableHash { + int hash; + + _MutableHash(this.hash); + + @override + bool operator ==(Object other) => + identical(this, other) || other is _MutableHash && hash == other.hash; + + @override + int get hashCode => hash; +} + void main() { group('Enum', () { test('enumFromName', () async { @@ -79,6 +93,26 @@ void main() { expect(s1.toList(), unorderedEquals(['b'])); }); + + test('element with a changing hashCode', () { + // Bucketed by `hashCode`, an element was looked up in another group + // after its `hashCode` changed: not found by `contains`/`remove`. + var s = IdenticalSet<_MutableHash>(groups: 7); + + var o = _MutableHash(1); + expect(s.add(o), isTrue); + + for (var h = 2; h <= 7; ++h) { + o.hash = h; + expect(s.contains(o), isTrue, reason: 'hash: $h'); + expect(s.add(o), isFalse, reason: 'hash: $h'); + } + + expect(s.length, equals(1)); + expect(s.remove(o), isTrue); + expect(s.isEmpty, isTrue); + expect(s.toList(), isEmpty); + }); }); group('isEqualsDeep', () {