Compare commits
No commits in common. "245321849a5880aacb63bf5f881a1bd17848d448" and "7fa2bb0f7eed9a9f1a079cf6503bb8f6b8f6ae00" have entirely different histories.
245321849a
...
7fa2bb0f7e
76 changed files with 328 additions and 4334 deletions
0
examples/app-template/.gitattributes
vendored
0
examples/app-template/.gitattributes
vendored
25
examples/app-template/.gitignore
vendored
25
examples/app-template/.gitignore
vendored
|
|
@ -1,25 +0,0 @@
|
|||
# See https://www.dartlang.org/guides/libraries/private-files
|
||||
|
||||
# Files and directories created by pub
|
||||
.dart_tool/
|
||||
.packages
|
||||
build/
|
||||
# If you're building an application, you may want to check-in your pubspec.lock
|
||||
pubspec.lock
|
||||
|
||||
# Ignore autosave files
|
||||
README.md~
|
||||
.gitignore~
|
||||
|
||||
# Directory created by dartdoc
|
||||
# If you don't generate documentation locally you can remove this line.
|
||||
doc/api/
|
||||
|
||||
# Avoid committing generated Javascript files:
|
||||
*.dart.js
|
||||
*.info.json # Produced by the --dump-info flag.
|
||||
*.js # When generated by dart2js. Don't specify *.js if your
|
||||
# project includes source files written in JavaScript.
|
||||
*.js_
|
||||
*.js.deps
|
||||
*.js.map
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
## 1.0.0
|
||||
|
||||
- Initial version.
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
|
||||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2024 Patrick Stewart
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/protevus/branding/main/protevus-logo-bg.png"></a></p>
|
||||
|
||||
## About Protevus
|
||||
|
||||
> **Note:** This repository provides a base application setup inspired by Laravel. If you want to contribute to the core Protevus Platform, visit the main [Protevus Platform repository](https://github.com/protevus/platform).
|
||||
|
||||
Protevus is a reference implementation that demonstrates how to build applications using the Protevus Platform. It serves as a starting point for developers to create their own applications leveraging the power and versatility of the Protevus Platform.
|
||||
|
||||
## Features
|
||||
|
||||
- **Laravel-inspired Structure**: The starter application follows a structure and conventions inspired by the Laravel framework, making it familiar to Laravel developers.
|
||||
- **Protevus Platform Integration**: The application is built on top of the Protevus Platform, providing a Laravel-compatible API and development experience.
|
||||
- **Example Components**: The repository includes example components such as controllers, middleware, and services, showcasing best practices and usage patterns.
|
||||
- **Extensibility**: Developers can easily extend and customize the starter application to meet their specific project requirements.
|
||||
|
||||
## Getting Started
|
||||
|
||||
To get started with the Protevus Starter Application, follow these steps:
|
||||
|
||||
1. **Install Dependencies**: Ensure you have the Dart SDK and the necessary dependencies installed on your system.
|
||||
2. **Clone the Repository**: Clone the Protevus Starter Application repository to your local machine.
|
||||
3. **Build and Run**: Follow the instructions in the repository's documentation to build and run the application.
|
||||
|
||||
## Documentation
|
||||
|
||||
Documentation for the Protevus Starter Application is available at [protevus.com/docs/protevus](https://protevus.com/docs/protevus). The documentation covers installation, configuration, customization, and deployment guides.
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions from the community! If you'd like to contribute to the Protevus Starter Application, please follow the guidelines outlined in the [CONTRIBUTING.md](CONTRIBUTING.md) file.
|
||||
|
||||
## License
|
||||
|
||||
The Protevus Application is released under the [MIT License](LICENSE).
|
||||
|
||||
## Support and Community
|
||||
|
||||
If you have any questions, issues, or suggestions, please join our community:
|
||||
|
||||
- **GitHub Discussions**: [github.com/protevus/protevus/discussions](https://github.com/protevus/protevus/discussions)
|
||||
- **Twitter**: [@Protevus](https://twitter.com/Protevus)
|
||||
|
||||
|
|
@ -1,30 +0,0 @@
|
|||
# This file configures the static analysis results for your project (errors,
|
||||
# warnings, and lints).
|
||||
#
|
||||
# This enables the 'recommended' set of lints from `package:lints`.
|
||||
# This set helps identify many issues that may lead to problems when running
|
||||
# or consuming Dart code, and enforces writing Dart using a single, idiomatic
|
||||
# style and format.
|
||||
#
|
||||
# If you want a smaller set of lints you can change this to specify
|
||||
# 'package:lints/core.yaml'. These are just the most critical lints
|
||||
# (the recommended set includes the core lints).
|
||||
# The core lints are also what is used by pub.dev for scoring packages.
|
||||
|
||||
include: package:lints/recommended.yaml
|
||||
|
||||
# Uncomment the following section to specify additional rules.
|
||||
|
||||
# linter:
|
||||
# rules:
|
||||
# - camel_case_types
|
||||
|
||||
# analyzer:
|
||||
# exclude:
|
||||
# - path/to/excluded/files/**
|
||||
|
||||
# For more information about the core and recommended set of lints, see
|
||||
# https://dart.dev/go/core-lints
|
||||
|
||||
# For additional information about configuring this file, see
|
||||
# https://dart.dev/guides/language/analysis-options
|
||||
|
|
@ -1,14 +0,0 @@
|
|||
{
|
||||
"$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.11.0/.schema/devbox.schema.json",
|
||||
"packages": ["dart@latest"],
|
||||
"shell": {
|
||||
"init_hook": [
|
||||
"echo 'Welcome to devbox!' > /dev/null"
|
||||
],
|
||||
"scripts": {
|
||||
"test": [
|
||||
"echo \"Error: no test specified\" && exit 1"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
{
|
||||
"lockfile_version": "1",
|
||||
"packages": {
|
||||
"dart@latest": {
|
||||
"last_modified": "2024-06-03T07:19:07Z",
|
||||
"resolved": "github:NixOS/nixpkgs/4a4ecb0ab415c9fccfb005567a215e6a9564cdf5#dart",
|
||||
"source": "devbox-search",
|
||||
"version": "3.4.2",
|
||||
"systems": {
|
||||
"aarch64-darwin": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/9piqr817cdsgmz31m8q723lxhcpgqsa4-dart-3.4.2",
|
||||
"default": true
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/9piqr817cdsgmz31m8q723lxhcpgqsa4-dart-3.4.2"
|
||||
},
|
||||
"aarch64-linux": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/1j3h5yqxvgzakv5gir1ssg7wggwxhmsd-dart-3.4.2",
|
||||
"default": true
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/1j3h5yqxvgzakv5gir1ssg7wggwxhmsd-dart-3.4.2"
|
||||
},
|
||||
"x86_64-darwin": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/k8a6gkss3s19p5dhbzgbdqqk5b8qzd7d-dart-3.4.2",
|
||||
"default": true
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/k8a6gkss3s19p5dhbzgbdqqk5b8qzd7d-dart-3.4.2"
|
||||
},
|
||||
"x86_64-linux": {
|
||||
"outputs": [
|
||||
{
|
||||
"name": "out",
|
||||
"path": "/nix/store/wbj1csi5fk2w99aiglwgg1mv406pw4pn-dart-3.4.2",
|
||||
"default": true
|
||||
}
|
||||
],
|
||||
"store_path": "/nix/store/wbj1csi5fk2w99aiglwgg1mv406pw4pn-dart-3.4.2"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -1,28 +0,0 @@
|
|||
name: app-template
|
||||
description: An absolute bare-bones protevus app.
|
||||
version: 1.0.0
|
||||
# repository: https://github.com/my_org/my_repo
|
||||
|
||||
environment:
|
||||
sdk: ^3.4.0
|
||||
|
||||
# Add regular dependencies here.
|
||||
dependencies:
|
||||
web: ^0.5.1
|
||||
|
||||
dev_dependencies:
|
||||
build_runner: ^2.4.8
|
||||
build_web_compilers: ^4.0.9
|
||||
lints: ^3.0.0
|
||||
|
||||
# Override default source directory
|
||||
source_directories:
|
||||
- app
|
||||
- bootstrap
|
||||
- config
|
||||
- database
|
||||
- public
|
||||
- resources
|
||||
- routes
|
||||
- storage
|
||||
- tests
|
||||
|
|
@ -2,7 +2,6 @@ name: protevus_platform
|
|||
repository: https://github.com/protevus/platform
|
||||
packages:
|
||||
- packages/**
|
||||
- examples/**
|
||||
|
||||
command:
|
||||
version:
|
||||
|
|
|
|||
|
|
@ -7,14 +7,6 @@
|
|||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
/// This library exports various components of the application framework.
|
||||
///
|
||||
/// It includes:
|
||||
/// - Application and ApplicationServer classes for managing the application lifecycle
|
||||
/// - Channel for handling request/response cycles
|
||||
/// - IsolateApplicationServer and IsolateSupervisor for managing isolates
|
||||
/// - Options for configuring the application
|
||||
/// - Starter for initializing and running the application
|
||||
library;
|
||||
|
||||
export 'src/application.dart';
|
||||
|
|
|
|||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:io';
|
||||
import 'dart:isolate';
|
||||
|
|
@ -20,138 +11,56 @@ export 'application_server.dart';
|
|||
export 'options.dart';
|
||||
export 'starter.dart';
|
||||
|
||||
/// The Application class is responsible for starting and managing instances of an ApplicationChannel.
|
||||
/// This object starts and stops instances of your [ApplicationChannel].
|
||||
///
|
||||
/// An application object opens HTTP listeners that forward requests to instances of your [ApplicationChannel].
|
||||
/// It is unlikely that you need to use this class directly - the `conduit serve` command creates an application object
|
||||
/// on your behalf.
|
||||
class Application<T extends ApplicationChannel> {
|
||||
/// A list of isolates that this application supervises.
|
||||
///
|
||||
/// This list contains [ApplicationIsolateSupervisor] instances, each representing
|
||||
/// an isolate running a separate instance of the application. These supervisors
|
||||
/// are responsible for managing the lifecycle and communication with their
|
||||
/// respective isolates. The list is populated when the application starts and
|
||||
/// is cleared when the application stops.
|
||||
List<ApplicationIsolateSupervisor> supervisors = [];
|
||||
|
||||
/// The [ApplicationServer] listening for HTTP requests while under test.
|
||||
///
|
||||
/// This property is only valid when an application is started via [startOnCurrentIsolate].
|
||||
/// It represents the server instance that handles incoming HTTP requests during testing.
|
||||
/// The server is initialized when the application starts on the current isolate and
|
||||
/// provides access to the underlying HTTP server and application channel.
|
||||
///
|
||||
/// Note: This property should not be accessed before calling [startOnCurrentIsolate],
|
||||
/// as it will not be initialized until then.
|
||||
late ApplicationServer server;
|
||||
|
||||
/// The [ApplicationChannel] handling requests while under test.
|
||||
///
|
||||
/// This property provides access to the application channel instance when the application
|
||||
/// is started using [startOnCurrentIsolate]. It allows direct interaction with the channel
|
||||
/// during testing, enabling access to its properties and methods.
|
||||
///
|
||||
/// The returned value is cast to type [T], which should match the generic type parameter
|
||||
/// of the [Application] class.
|
||||
///
|
||||
/// This property is only valid and accessible after calling [startOnCurrentIsolate].
|
||||
/// Attempting to access it before starting the application or when using [start] instead
|
||||
/// of [startOnCurrentIsolate] may result in unexpected behavior or errors.
|
||||
///
|
||||
/// Usage example:
|
||||
/// ```dart
|
||||
/// final app = Application<MyChannel>();
|
||||
/// await app.startOnCurrentIsolate();
|
||||
/// final myChannel = app.channel;
|
||||
/// // Now you can interact with myChannel for testing purposes
|
||||
/// ```
|
||||
/// This property is only valid when an application is started via [startOnCurrentIsolate]. You use
|
||||
/// this value to access elements of your application channel during testing.
|
||||
T get channel => server.channel as T;
|
||||
|
||||
/// The logger that this application will write messages to.
|
||||
///
|
||||
/// This logger is used throughout the application to record messages, errors,
|
||||
/// and other important information. It is configured with the name 'protevus',
|
||||
/// which will appear as the source of all log messages generated by this logger.
|
||||
///
|
||||
/// The Logger class is likely from a logging package, providing various methods
|
||||
/// for different log levels (e.g., info, warning, error) and potentially
|
||||
/// supporting different output destinations or formatting options.
|
||||
///
|
||||
/// Usage of this logger helps in debugging, monitoring, and maintaining the
|
||||
/// application by providing a centralized way to capture and analyze runtime
|
||||
/// information.
|
||||
Logger logger = Logger("protevus");
|
||||
/// This logger's name will appear as 'conduit'.
|
||||
Logger logger = Logger("conduit");
|
||||
|
||||
/// The options used to configure this application.
|
||||
///
|
||||
/// This property holds an instance of [ApplicationOptions] that contains various
|
||||
/// configuration settings for the application. These options can include things
|
||||
/// like port numbers, database configurations, or any other application-specific
|
||||
/// settings.
|
||||
///
|
||||
/// The options are typically set before the application is started. It's important
|
||||
/// to note that modifying these options after the application has been started
|
||||
/// will not have any effect on the running application.
|
||||
///
|
||||
/// Example usage:
|
||||
/// ```dart
|
||||
/// final app = Application<MyChannel>();
|
||||
/// app.options.port = 8080;
|
||||
/// app.options.configurationFilePath = 'config.yaml';
|
||||
/// await app.start();
|
||||
/// ```
|
||||
///
|
||||
/// Default value is an instance of [ApplicationOptions] with default settings.
|
||||
/// Changing these values once the application has started will have no effect.
|
||||
ApplicationOptions options = ApplicationOptions();
|
||||
|
||||
/// The duration to wait for each isolate during startup before failing.
|
||||
///
|
||||
/// This property sets the maximum time allowed for each isolate to start up
|
||||
/// during the application's initialization process. If an isolate fails to
|
||||
/// complete its startup within this time frame, a [TimeoutException] is thrown.
|
||||
/// A [TimeoutException] is thrown if an isolate fails to startup in this time period.
|
||||
///
|
||||
/// Defaults to 30 seconds.
|
||||
Duration isolateStartupTimeout = const Duration(seconds: 30);
|
||||
|
||||
/// Indicates whether the application is currently running.
|
||||
/// Whether or not this application is running.
|
||||
///
|
||||
/// This will return true if [start]/[startOnCurrentIsolate] have been invoked and completed; i.e. this is the synchronous version of the [Future] returned by [start]/[startOnCurrentIsolate].
|
||||
///
|
||||
/// This value will return to false after [stop] has completed.
|
||||
bool get isRunning => _hasFinishedLaunching;
|
||||
|
||||
/// Indicates whether the application has finished launching.
|
||||
///
|
||||
/// This boolean flag is set to true once the application has successfully
|
||||
/// completed its startup process, including initializing all isolates and
|
||||
/// opening HTTP listeners. It is used internally to track the application's
|
||||
/// running state and is consulted by the [isRunning] getter.
|
||||
///
|
||||
/// The value is set to false initially and when the application is stopped,
|
||||
/// and set to true at the end of successful [start] or [startOnCurrentIsolate]
|
||||
/// method execution.
|
||||
bool _hasFinishedLaunching = false;
|
||||
|
||||
/// Retrieves the [ChannelRuntime] for the current application channel type.
|
||||
///
|
||||
/// This getter accesses the [RuntimeContext.current] map using the generic type [T]
|
||||
/// (which represents the application's channel type) as the key. It then casts
|
||||
/// the retrieved value to [ChannelRuntime].
|
||||
///
|
||||
/// The [ChannelRuntime] object contains runtime information and utilities
|
||||
/// specific to the channel type, which are used in various parts of the
|
||||
/// application for setup, initialization, and execution.
|
||||
///
|
||||
/// This getter is used internally by the Application class to access
|
||||
/// channel-specific runtime information without exposing it publicly.
|
||||
ChannelRuntime get _runtime => RuntimeContext.current[T] as ChannelRuntime;
|
||||
|
||||
/// Starts this application, allowing it to handle HTTP requests.
|
||||
///
|
||||
/// This method initializes the application by spawning a specified number of isolates,
|
||||
/// each running an instance of the application channel. It then sets up an HTTP listener
|
||||
/// to distribute incoming requests across these isolates.
|
||||
/// This method spawns [numberOfInstances] isolates, instantiates your application channel
|
||||
/// for each of these isolates, and opens an HTTP listener that sends requests to these instances.
|
||||
///
|
||||
/// The [Future] returned from this method will complete once all isolates have successfully started
|
||||
/// and are available to handle requests.
|
||||
|
|
@ -201,7 +110,7 @@ class Application<T extends ApplicationChannel> {
|
|||
_hasFinishedLaunching = true;
|
||||
}
|
||||
|
||||
/// Starts the application on the current isolate without spawning additional isolates.
|
||||
/// Starts the application on the current isolate, and does not spawn additional isolates.
|
||||
///
|
||||
/// An application started in this way will run on the same isolate this method is invoked on.
|
||||
/// Performance is limited when running the application with this method; prefer to use [start].
|
||||
|
|
@ -230,20 +139,8 @@ class Application<T extends ApplicationChannel> {
|
|||
|
||||
/// Stops the application from running.
|
||||
///
|
||||
/// This method performs the following actions:
|
||||
/// 1. Sets the '_hasFinishedLaunching' flag to false.
|
||||
/// 2. Stops all supervisor isolates concurrently.
|
||||
/// 3. Handles potential errors during supervisor shutdown, particularly checking for 'LateError'.
|
||||
/// 4. Attempts to close the server forcefully.
|
||||
/// 5. Logs any errors that occur during server closure.
|
||||
/// 6. Resets the '_hasFinishedLaunching' flag and clears the supervisors list.
|
||||
/// 7. Removes all listeners from the logger.
|
||||
///
|
||||
/// If a 'LateError' is encountered during supervisor shutdown, it throws a [StateError]
|
||||
/// indicating that the channel type was not properly loaded.
|
||||
///
|
||||
/// This method ensures a clean shutdown of all application components and should be
|
||||
/// called when the application needs to be terminated.
|
||||
/// Closes every isolate and their channel and stops listening for HTTP requests.
|
||||
/// The [ServiceRegistry] will close any of its resources.
|
||||
Future stop() async {
|
||||
_hasFinishedLaunching = false;
|
||||
await Future.wait(supervisors.map((s) => s.stop()))
|
||||
|
|
@ -270,26 +167,6 @@ class Application<T extends ApplicationChannel> {
|
|||
|
||||
/// Creates an [APIDocument] from an [ApplicationChannel].
|
||||
///
|
||||
/// This static method generates API documentation for a given application channel type.
|
||||
/// It is primarily used by the 'conduit document' CLI command to create OpenAPI (formerly Swagger) documentation.
|
||||
///
|
||||
/// The method performs the following steps:
|
||||
/// 1. Retrieves the runtime context for the specified channel type.
|
||||
/// 2. Runs global initialization with the provided configuration.
|
||||
/// 3. Creates an ApplicationServer instance.
|
||||
/// 4. Prepares the channel.
|
||||
/// 5. Generates the API documentation.
|
||||
/// 6. Closes the channel.
|
||||
/// 7. Returns the generated APIDocument.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [type]: The Type of the ApplicationChannel subclass.
|
||||
/// - [config]: The ApplicationOptions containing configuration for the application.
|
||||
/// - [projectSpec]: A Map containing additional project-specific information for the documentation.
|
||||
///
|
||||
/// Returns:
|
||||
/// A Future that resolves to an [APIDocument] containing the generated API documentation.
|
||||
///
|
||||
/// This method is called by the `conduit document` CLI.
|
||||
static Future<APIDocument> document(
|
||||
Type type,
|
||||
|
|
@ -311,25 +188,6 @@ class Application<T extends ApplicationChannel> {
|
|||
return doc;
|
||||
}
|
||||
|
||||
/// Spawns a new isolate to run an instance of the application.
|
||||
///
|
||||
/// This method creates a new isolate that runs an instance of the application channel.
|
||||
/// It sets up the necessary communication channels and initializes the isolate with
|
||||
/// the application's configuration and runtime information.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [application]: The main Application instance.
|
||||
/// - [config]: ApplicationOptions containing the configuration for this instance.
|
||||
/// - [identifier]: A unique identifier for this isolate.
|
||||
/// - [logger]: The Logger instance for logging.
|
||||
/// - [startupTimeout]: The maximum duration allowed for the isolate to start up.
|
||||
/// - [logToConsole]: Whether to enable console logging for this isolate (default: false).
|
||||
///
|
||||
/// Returns:
|
||||
/// A Future that resolves to an [ApplicationIsolateSupervisor] managing the new isolate.
|
||||
///
|
||||
/// This method is crucial for scaling the application across multiple isolates,
|
||||
/// allowing for better performance and resource utilization.
|
||||
Future<ApplicationIsolateSupervisor> _spawn(
|
||||
Application application,
|
||||
ApplicationOptions config,
|
||||
|
|
@ -366,7 +224,7 @@ class Application<T extends ApplicationChannel> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Represents an exception that occurs during the startup process of an application.
|
||||
/// Thrown when an application encounters an exception during startup.
|
||||
///
|
||||
/// Contains the original exception that halted startup.
|
||||
class ApplicationStartupException implements Exception {
|
||||
|
|
|
|||
|
|
@ -1,38 +1,17 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:io';
|
||||
import 'package:logging/logging.dart';
|
||||
import 'package:protevus_application/application.dart';
|
||||
import 'package:protevus_http/http.dart';
|
||||
import 'package:protevus_runtime/runtime.dart';
|
||||
import 'package:logging/logging.dart';
|
||||
|
||||
/// A class representing an application server in the Conduit framework.
|
||||
/// Listens for HTTP requests and delivers them to its [ApplicationChannel] instance.
|
||||
///
|
||||
/// The ApplicationServer class is responsible for managing the lifecycle of an HTTP server
|
||||
/// and its associated [ApplicationChannel]. It handles server creation, starting, and stopping,
|
||||
/// as well as routing incoming requests to the appropriate handlers.
|
||||
///
|
||||
/// Key features:
|
||||
/// - Creates and manages an instance of [ApplicationChannel]
|
||||
/// - Configures and starts an HTTP or HTTPS server
|
||||
/// - Handles incoming requests and routes them to the appropriate controller
|
||||
/// - Manages server lifecycle (start, stop, close)
|
||||
/// - Provides logging capabilities
|
||||
/// - Supports both IPv4 and IPv6
|
||||
/// - Handles secure connections with SSL/TLS
|
||||
///
|
||||
/// This class is typically instantiated and managed by the Application class and should not
|
||||
/// be created directly in most cases
|
||||
/// A Conduit application creates instances of this type to pair an HTTP server and an
|
||||
/// instance of an [ApplicationChannel] subclass. Instances are created by [Application]
|
||||
/// and shouldn't be created otherwise.
|
||||
class ApplicationServer {
|
||||
/// Creates a new server instance.
|
||||
/// Creates a new server.
|
||||
///
|
||||
/// You should not need to invoke this method directly.
|
||||
ApplicationServer(this.channelType, this.options, this.identifier) {
|
||||
|
|
@ -42,145 +21,41 @@ class ApplicationServer {
|
|||
..options = options;
|
||||
}
|
||||
|
||||
/// The configuration options used to start this server's [channel].
|
||||
///
|
||||
/// This property holds an instance of [ApplicationOptions] which contains
|
||||
/// various settings used to configure the server, such as the address to bind to,
|
||||
/// the port number, SSL/TLS settings, and other application-specific options.
|
||||
/// These options are passed to the [ApplicationChannel] when it is initialized.
|
||||
/// The configuration this instance used to start its [channel].
|
||||
ApplicationOptions options;
|
||||
|
||||
/// The underlying [HttpServer] instance used by this [ApplicationServer].
|
||||
///
|
||||
/// This property represents the core HTTP server that handles incoming requests.
|
||||
/// It is initialized when the server starts and is used throughout the lifecycle
|
||||
/// of the [ApplicationServer] to manage incoming connections and route requests
|
||||
/// to the appropriate handlers.
|
||||
///
|
||||
/// The server can be either a standard HTTP server or an HTTPS server, depending
|
||||
/// on the configuration and security context provided during initialization.
|
||||
/// The underlying [HttpServer].
|
||||
late final HttpServer server;
|
||||
|
||||
/// The instance of [ApplicationChannel] serving requests.
|
||||
///
|
||||
/// This property represents the primary request handling pipeline for the application.
|
||||
/// It is instantiated when the ApplicationServer is created and is responsible for
|
||||
/// processing incoming HTTP requests, routing them to appropriate controllers,
|
||||
/// and generating responses.
|
||||
///
|
||||
/// The [ApplicationChannel] is a custom class defined by the application developer
|
||||
/// that sets up the request handling logic, including middleware, controllers,
|
||||
/// and other application-specific components.
|
||||
late ApplicationChannel channel;
|
||||
|
||||
/// The cached entrypoint of [channel].
|
||||
///
|
||||
/// This property stores the main [Controller] that serves as the entry point for request handling.
|
||||
/// It is initialized when the server starts and is used to process incoming HTTP requests.
|
||||
/// The entrypoint controller typically represents the root of the request handling pipeline
|
||||
/// and may delegate to other controllers or middleware as needed.
|
||||
late Controller entryPoint;
|
||||
|
||||
/// The type of [ApplicationChannel] this server will use.
|
||||
///
|
||||
/// This property stores the Type of the ApplicationChannel subclass that will be
|
||||
/// instantiated and used by this ApplicationServer. The ApplicationChannel
|
||||
/// defines the request handling logic and routing for the application.
|
||||
final Type channelType;
|
||||
|
||||
/// Target for sending messages to other [ApplicationChannel.messageHub]s.
|
||||
///
|
||||
/// This property represents an [EventSink] that can be used to send messages
|
||||
/// to other [ApplicationChannel.messageHub]s across different instances of
|
||||
/// the application. It is primarily used for inter-server communication in
|
||||
/// distributed setups.
|
||||
///
|
||||
/// The [hubSink] is typically set and managed by instances of [ApplicationMessageHub].
|
||||
/// Application developers should not directly modify or use this property, as it is
|
||||
/// intended for internal framework use.
|
||||
///
|
||||
/// The sink can be null if no message hub has been configured for this server.
|
||||
/// Events are added to this property by instances of [ApplicationMessageHub] and should not otherwise be used.
|
||||
EventSink<dynamic>? hubSink;
|
||||
|
||||
/// Indicates whether this server requires an HTTPS listener.
|
||||
///
|
||||
/// This getter returns a boolean value that determines if the server
|
||||
/// should use HTTPS instead of HTTP. It is typically set to true when
|
||||
/// a security context is provided during server initialization.
|
||||
///
|
||||
/// Returns:
|
||||
/// [bool]: true if the server requires HTTPS, false otherwise.
|
||||
/// Whether or not this server requires an HTTPS listener.
|
||||
bool get requiresHTTPS => _requiresHTTPS;
|
||||
|
||||
/// Indicates whether this server instance is configured to use HTTPS.
|
||||
///
|
||||
/// This private variable is set to true when a security context is provided
|
||||
/// during server initialization, indicating that the server should use HTTPS.
|
||||
/// It is used internally to determine the server's connection type and is
|
||||
/// accessed through the public getter [requiresHTTPS].
|
||||
///
|
||||
/// The value is false by default, assuming HTTP connection, and is only set to
|
||||
/// true when HTTPS is explicitly configured.
|
||||
bool _requiresHTTPS = false;
|
||||
|
||||
/// The unique identifier of this instance.
|
||||
///
|
||||
/// Each instance has its own identifier, a numeric value starting at 1, to identify it
|
||||
/// among other instances.
|
||||
///
|
||||
/// This identifier is used to distinguish between different [ApplicationServer] instances
|
||||
/// when multiple servers are running concurrently. It's particularly useful for logging
|
||||
/// and debugging purposes, allowing developers to trace which server instance is handling
|
||||
/// specific requests or operations.
|
||||
///
|
||||
/// The identifier is typically assigned automatically by the [Application] class when
|
||||
/// creating new server instances, ensuring that each server has a unique number.
|
||||
///
|
||||
/// Example:
|
||||
/// If three server instances are created, they might have identifiers 1, 2, and 3 respectively.
|
||||
int identifier;
|
||||
|
||||
/// Returns the logger instance for this ApplicationServer.
|
||||
///
|
||||
/// This getter provides access to a [Logger] instance specifically configured
|
||||
/// for the Conduit framework. The logger is named "conduit" and can be used
|
||||
/// throughout the ApplicationServer and its associated classes for consistent
|
||||
/// logging purposes.
|
||||
///
|
||||
/// The logger can be used to record various levels of information, warnings,
|
||||
/// and errors during the server's operation, which is crucial for debugging
|
||||
/// and monitoring the application's behavior.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [Logger] instance named "conduit".
|
||||
Logger get logger => Logger("protevus");
|
||||
/// The logger of this instance
|
||||
Logger get logger => Logger("conduit");
|
||||
|
||||
/// Starts this instance, allowing it to receive HTTP requests.
|
||||
///
|
||||
/// This method initializes the server, preparing it to handle incoming HTTP requests.
|
||||
/// It performs the following steps:
|
||||
/// 1. Prepares the channel by calling [channel.prepare()].
|
||||
/// 2. Sets up the entry point for request handling.
|
||||
/// 3. Binds the HTTP server to the specified address and port.
|
||||
/// 4. Configures HTTPS if a security context is provided.
|
||||
///
|
||||
/// The method supports both HTTP and HTTPS connections, determined by the presence
|
||||
/// of a security context. It also handles IPv6 configuration and server sharing options.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [shareHttpServer] - A boolean indicating whether to share the HTTP server
|
||||
/// across multiple instances. Defaults to false.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [Future] that completes when the server has successfully started and is
|
||||
/// ready to receive requests.
|
||||
///
|
||||
/// Throws:
|
||||
/// May throw exceptions related to network binding or security context configuration.
|
||||
///
|
||||
/// Note:
|
||||
/// This method should not be invoked directly under normal circumstances.
|
||||
/// It is typically called by the framework during the application startup process.
|
||||
/// Do not invoke this method directly.
|
||||
Future start({bool shareHttpServer = false}) async {
|
||||
logger.fine("ApplicationServer($identifier).start entry");
|
||||
|
||||
|
|
@ -217,21 +92,7 @@ class ApplicationServer {
|
|||
return didOpen();
|
||||
}
|
||||
|
||||
/// Closes this HTTP server and associated channel.
|
||||
///
|
||||
/// This method performs the following steps:
|
||||
/// 1. Closes the HTTP server, forcibly terminating any ongoing connections.
|
||||
/// 2. Closes the associated [ApplicationChannel].
|
||||
/// 3. Closes the [hubSink] if it exists.
|
||||
///
|
||||
/// The method logs the progress of each step for debugging purposes.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [Future] that completes when all closing operations are finished.
|
||||
///
|
||||
/// Note:
|
||||
/// The [hubSink] is actually closed by channel.messageHub.close, but it's
|
||||
/// explicitly closed here to satisfy the Dart analyzer.
|
||||
/// Closes this HTTP server and channel.
|
||||
Future close() async {
|
||||
logger.fine("ApplicationServer($identifier).close Closing HTTP listener");
|
||||
await server.close(force: true);
|
||||
|
|
@ -243,7 +104,7 @@ class ApplicationServer {
|
|||
logger.fine("ApplicationServer($identifier).close Closing complete");
|
||||
}
|
||||
|
||||
/// Invoked when this server becomes ready to receive requests.
|
||||
/// Invoked when this server becomes ready receive requests.
|
||||
///
|
||||
/// [ApplicationChannel.willStartReceivingRequests] is invoked after this opening has completed.
|
||||
Future didOpen() async {
|
||||
|
|
@ -256,18 +117,6 @@ class ApplicationServer {
|
|||
logger.info("Server conduit/$identifier started.");
|
||||
}
|
||||
|
||||
/// Sends an application event.
|
||||
///
|
||||
/// This method is designed to handle application-wide events. By default,
|
||||
/// it does nothing and serves as a placeholder for potential event handling
|
||||
/// implementations in derived classes.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [event]: A dynamic object representing the event to be sent.
|
||||
/// It can be of any type, allowing flexibility in event structures.
|
||||
///
|
||||
/// Note:
|
||||
/// Override this method in subclasses to implement specific event handling logic.
|
||||
void sendApplicationEvent(dynamic event) {
|
||||
// By default, do nothing
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:io';
|
||||
|
||||
|
|
@ -18,7 +9,7 @@ import 'package:protevus_runtime/runtime.dart';
|
|||
import 'package:logging/logging.dart';
|
||||
import 'package:meta/meta.dart';
|
||||
|
||||
/// An abstract class that defines the behavior specific to your application.
|
||||
/// An object that defines the behavior specific to your application.
|
||||
///
|
||||
/// You create a subclass of [ApplicationChannel] to initialize your application's services and define how HTTP requests are handled by your application.
|
||||
/// There *must* only be one subclass in an application and it must be visible to your application library file, e.g., 'package:my_app/my_app.dart'.
|
||||
|
|
@ -30,7 +21,7 @@ import 'package:meta/meta.dart';
|
|||
/// When your application is started, an instance of your application channel is created for each isolate (see [Application.start]). Each instance
|
||||
/// is a replica of your application that runs in its own memory isolated thread.
|
||||
abstract class ApplicationChannel implements APIComponentDocumenter {
|
||||
/// Provides global initialization for the application.
|
||||
/// You implement this method to provide global initialization for your application.
|
||||
///
|
||||
/// Most of your application initialization code is written in [prepare], which is invoked for each isolate. For initialization that
|
||||
/// needs to occur once per application start, you must provide an implementation for this method. This method is invoked prior
|
||||
|
|
@ -60,43 +51,27 @@ abstract class ApplicationChannel implements APIComponentDocumenter {
|
|||
/// is for documentation purposes.
|
||||
static Future initializeApplication(ApplicationOptions options) async {}
|
||||
|
||||
/// Returns a Logger instance for this object.
|
||||
/// The logger that this object will write messages to.
|
||||
///
|
||||
/// This logger's name appears as 'conduit'.
|
||||
Logger get logger => Logger("protevus");
|
||||
Logger get logger => Logger("conduit");
|
||||
|
||||
/// Returns the [ApplicationServer] instance that sends HTTP requests to this object.
|
||||
///
|
||||
/// This getter provides access to the server associated with this ApplicationChannel.
|
||||
/// The server is responsible for handling incoming HTTP requests and routing them
|
||||
/// to the appropriate controllers within the channel.
|
||||
/// The [ApplicationServer] that sends HTTP requests to this object.
|
||||
ApplicationServer get server => _server;
|
||||
|
||||
/// Sets the ApplicationServer for this channel and establishes message hub connections.
|
||||
///
|
||||
/// This setter method performs two main tasks:
|
||||
/// 1. It assigns the provided [server] to the private [_server] variable.
|
||||
/// 2. It sets up the message hub connections:
|
||||
/// - It adds a listener to the outbound stream of the messageHub, which sends
|
||||
/// application events through the server.
|
||||
/// - It sets the inbound sink of the messageHub as the hubSink of the server.
|
||||
///
|
||||
/// This setup allows for inter-isolate communication through the ApplicationMessageHub.
|
||||
///
|
||||
/// [server] The ApplicationServer instance to be set for this channel.
|
||||
set server(ApplicationServer server) {
|
||||
_server = server;
|
||||
messageHub._outboundController.stream.listen(server.sendApplicationEvent);
|
||||
server.hubSink = messageHub._inboundController.sink;
|
||||
}
|
||||
|
||||
/// A messaging hub for inter-isolate communication within the application.
|
||||
/// Use this object to send data to channels running on other isolates.
|
||||
///
|
||||
/// You use this object to synchronize state across the isolates of an application. Any data sent
|
||||
/// through this object will be received by every other channel in your application (except the one that sent it).
|
||||
final ApplicationMessageHub messageHub = ApplicationMessageHub();
|
||||
|
||||
/// Returns a SecurityContext for HTTPS configuration if certificate and private key files are provided.
|
||||
/// The context used for setting up HTTPS in an application.
|
||||
///
|
||||
/// If this value is non-null, the [server] receiving HTTP requests will only accept requests over HTTPS.
|
||||
///
|
||||
|
|
@ -118,17 +93,6 @@ abstract class ApplicationChannel implements APIComponentDocumenter {
|
|||
///
|
||||
/// These options are set when starting the application. Changes to this object have no effect
|
||||
/// on other isolates.
|
||||
///
|
||||
/// This property holds an instance of [ApplicationOptions] which contains various
|
||||
/// configuration settings for the application. These options are typically set
|
||||
/// during the application's startup process.
|
||||
///
|
||||
/// The options stored here are specific to this channel instance and do not
|
||||
/// affect other isolates running in the application. This means that modifying
|
||||
/// these options at runtime will only impact the current isolate.
|
||||
///
|
||||
/// The property is nullable, allowing for cases where options might not be set
|
||||
/// or where default configurations are used in the absence of specific options.
|
||||
ApplicationOptions? options;
|
||||
|
||||
/// You implement this accessor to define how HTTP requests are handled by your application.
|
||||
|
|
@ -148,17 +112,9 @@ abstract class ApplicationChannel implements APIComponentDocumenter {
|
|||
/// }
|
||||
Controller get entryPoint;
|
||||
|
||||
/// The [ApplicationServer] instance associated with this channel.
|
||||
///
|
||||
/// This private variable stores the server that handles HTTP requests for this
|
||||
/// ApplicationChannel. It is marked as 'late' because it will be initialized
|
||||
/// after the channel is created, typically when the 'server' setter is called.
|
||||
///
|
||||
/// The server is responsible for managing incoming HTTP connections and
|
||||
/// routing requests to the appropriate controllers within the channel.
|
||||
late ApplicationServer _server;
|
||||
|
||||
/// Performs initialization tasks for the application channel.
|
||||
/// You override this method to perform initialization tasks.
|
||||
///
|
||||
/// This method allows this instance to perform any initialization (other than setting up the [entryPoint]). This method
|
||||
/// is often used to set up services that [Controller]s use to fulfill their duties. This method is invoked
|
||||
|
|
@ -167,12 +123,12 @@ abstract class ApplicationChannel implements APIComponentDocumenter {
|
|||
/// By default, this method does nothing.
|
||||
Future prepare() async {}
|
||||
|
||||
/// Overridable method called just before the application starts receiving requests.
|
||||
/// You override this method to perform initialization tasks that occur after [entryPoint] has been established.
|
||||
///
|
||||
/// Override this method to take action just before [entryPoint] starts receiving requests. By default, does nothing.
|
||||
void willStartReceivingRequests() {}
|
||||
|
||||
/// Releases resources and performs cleanup when the application channel is closing.
|
||||
/// You override this method to release any resources created in [prepare].
|
||||
///
|
||||
/// This method is invoked when the owning [Application] is stopped. It closes open ports
|
||||
/// that this channel was using so that the application can be properly shut down.
|
||||
|
|
@ -190,8 +146,7 @@ abstract class ApplicationChannel implements APIComponentDocumenter {
|
|||
|
||||
/// Creates an OpenAPI document for the components and paths in this channel.
|
||||
///
|
||||
/// This method generates a complete OpenAPI specification document for the application,
|
||||
/// including all components, paths, and operations defined in the channel.
|
||||
/// This method invokes [entryPoint] and [prepare] before starting the documentation process.
|
||||
///
|
||||
/// The documentation process first invokes [documentComponents] on this channel. Every controller in the channel will have its
|
||||
/// [documentComponents] methods invoked. Any declared property
|
||||
|
|
@ -226,24 +181,6 @@ abstract class ApplicationChannel implements APIComponentDocumenter {
|
|||
return doc;
|
||||
}
|
||||
|
||||
/// Documents the components of this ApplicationChannel and its controllers.
|
||||
///
|
||||
/// This method is responsible for generating API documentation for the components
|
||||
/// of this ApplicationChannel and its associated controllers. It performs the following tasks:
|
||||
///
|
||||
/// 1. Calls `documentComponents` on the entry point controller, which typically
|
||||
/// initiates the documentation process for all linked controllers.
|
||||
///
|
||||
/// 2. Retrieves all documentable channel components using the ChannelRuntime,
|
||||
/// which are typically services or other objects that implement APIComponentDocumenter.
|
||||
///
|
||||
/// 3. Calls `documentComponents` on each of these channel components, allowing
|
||||
/// them to add their own documentation to the API registry.
|
||||
///
|
||||
/// This method is marked with @mustCallSuper, indicating that subclasses
|
||||
/// overriding this method must call the superclass implementation.
|
||||
///
|
||||
/// [registry] The APIDocumentContext used to store and organize the API documentation.
|
||||
@mustCallSuper
|
||||
@override
|
||||
void documentComponents(APIDocumentContext registry) {
|
||||
|
|
@ -257,7 +194,7 @@ abstract class ApplicationChannel implements APIComponentDocumenter {
|
|||
}
|
||||
}
|
||||
|
||||
/// An object that facilitates message passing between [ApplicationChannel]s in different isolates.
|
||||
/// An object that sends and receives messages between [ApplicationChannel]s.
|
||||
///
|
||||
/// You use this object to share information between isolates. Each [ApplicationChannel] has a property of this type. A message sent through this object
|
||||
/// is received by every other channel through its hub.
|
||||
|
|
@ -281,44 +218,14 @@ abstract class ApplicationChannel implements APIComponentDocumenter {
|
|||
/// }
|
||||
/// });
|
||||
class ApplicationMessageHub extends Stream<dynamic> implements Sink<dynamic> {
|
||||
/// A logger instance for the ApplicationMessageHub.
|
||||
///
|
||||
/// This logger is used to log messages and errors related to the ApplicationMessageHub.
|
||||
/// It is named "protevus" to identify logs from this specific component.
|
||||
final Logger _logger = Logger("protevus");
|
||||
|
||||
/// A StreamController for outbound messages.
|
||||
///
|
||||
/// This controller manages the stream of outbound messages sent from this
|
||||
/// ApplicationMessageHub to other hubs. It is used internally to handle
|
||||
/// the flow of messages being sent out to other isolates.
|
||||
///
|
||||
/// The stream is not broadcast, meaning it only allows a single subscriber.
|
||||
/// This is typically used by the ApplicationServer to listen for outbound
|
||||
/// messages and distribute them to other isolates.
|
||||
final Logger _logger = Logger("conduit");
|
||||
final StreamController<dynamic> _outboundController =
|
||||
StreamController<dynamic>();
|
||||
|
||||
/// A StreamController for inbound messages.
|
||||
///
|
||||
/// This controller manages the stream of inbound messages received by this
|
||||
/// ApplicationMessageHub from other hubs. It is used internally to handle
|
||||
/// the flow of messages coming in from other isolates.
|
||||
///
|
||||
/// The stream is broadcast, meaning it allows multiple subscribers. This allows
|
||||
/// multiple parts of the application to listen for and react to incoming messages
|
||||
/// independently.
|
||||
final StreamController<dynamic> _inboundController =
|
||||
StreamController<dynamic>.broadcast();
|
||||
|
||||
/// Adds a listener for messages from other hubs.
|
||||
///
|
||||
/// A class that facilitates message passing between [ApplicationChannel]s in different isolates.
|
||||
///
|
||||
/// This class implements both [Stream] and [Sink] interfaces, allowing it to send and receive messages
|
||||
/// across isolates. It uses separate controllers for inbound and outbound messages to manage the flow
|
||||
/// of data.
|
||||
///
|
||||
/// You use this method to add listeners for messages from other hubs.
|
||||
/// When another hub [add]s a message, this hub will receive it on [onData].
|
||||
///
|
||||
|
|
@ -342,8 +249,7 @@ class ApplicationMessageHub extends Stream<dynamic> implements Sink<dynamic> {
|
|||
|
||||
/// Sends a message to all other hubs.
|
||||
///
|
||||
/// This method allows sending a message [event] to all other isolates in the application.
|
||||
/// The message will be delivered to all other isolates that have set up a callback using [listen].
|
||||
/// [event] will be delivered to all other isolates that have set up a callback for [listen].
|
||||
///
|
||||
/// [event] must be isolate-safe data - in general, this means it may not be or contain a closure. Consult the API reference `dart:isolate` for more details. If [event]
|
||||
/// is not isolate-safe data, an error is delivered to [listen] on this isolate.
|
||||
|
|
@ -352,19 +258,6 @@ class ApplicationMessageHub extends Stream<dynamic> implements Sink<dynamic> {
|
|||
_outboundController.sink.add(event);
|
||||
}
|
||||
|
||||
/// Closes the message hub and its associated stream controllers.
|
||||
///
|
||||
/// This method performs the following tasks:
|
||||
/// 1. If the outbound controller has no listeners, it adds a dummy listener
|
||||
/// to prevent potential issues with unhandled stream events.
|
||||
/// 2. If the inbound controller has no listeners, it adds a dummy listener
|
||||
/// for the same reason.
|
||||
/// 3. Closes both the outbound and inbound controllers.
|
||||
///
|
||||
/// This method should be called when the application is shutting down or
|
||||
/// when the message hub is no longer needed to ensure proper cleanup of resources.
|
||||
///
|
||||
/// Returns a Future that completes when both controllers have been closed.
|
||||
@override
|
||||
Future close() async {
|
||||
if (!_outboundController.hasListener) {
|
||||
|
|
@ -380,10 +273,6 @@ class ApplicationMessageHub extends Stream<dynamic> implements Sink<dynamic> {
|
|||
}
|
||||
}
|
||||
|
||||
/// An abstract class that defines the runtime behavior of an ApplicationChannel.
|
||||
///
|
||||
/// This class provides methods and properties for managing the lifecycle,
|
||||
/// documentation, and instantiation of an ApplicationChannel.
|
||||
abstract class ChannelRuntime {
|
||||
Iterable<APIComponentDocumenter> getDocumentableChannelComponents(
|
||||
ApplicationChannel channel,
|
||||
|
|
|
|||
|
|
@ -1,47 +1,10 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:isolate';
|
||||
import 'package:logging/logging.dart';
|
||||
import 'package:protevus_application/application.dart';
|
||||
|
||||
/// An isolated server implementation of the ApplicationServer class.
|
||||
///
|
||||
/// This class extends ApplicationServer to run in a separate isolate, allowing
|
||||
/// for concurrent execution of multiple server instances. It manages communication
|
||||
/// with a supervising application through message passing.
|
||||
///
|
||||
/// The server can be started, stopped, and can send and receive application events.
|
||||
/// It also supports optional console logging for debugging purposes.
|
||||
///
|
||||
/// Constructor parameters:
|
||||
/// - channelType: The type of channel to be used.
|
||||
/// - configuration: ApplicationOptions for server configuration.
|
||||
/// - identifier: A unique identifier for this server instance.
|
||||
/// - supervisingApplicationPort: SendPort for communicating with the supervising application.
|
||||
/// - logToConsole: Optional flag to enable console logging (default is false).
|
||||
import 'package:protevus_application/application.dart';
|
||||
import 'package:logging/logging.dart';
|
||||
|
||||
class ApplicationIsolateServer extends ApplicationServer {
|
||||
/// Constructor for ApplicationIsolateServer.
|
||||
///
|
||||
/// Creates a new instance of ApplicationIsolateServer with the specified parameters.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - channelType: The type of channel to be used for communication.
|
||||
/// - configuration: ApplicationOptions for configuring the server.
|
||||
/// - identifier: A unique identifier for this server instance.
|
||||
/// - supervisingApplicationPort: SendPort for communicating with the supervising application.
|
||||
/// - logToConsole: Optional flag to enable console logging (default is false).
|
||||
///
|
||||
/// This constructor initializes the server, sets up logging if enabled, and establishes
|
||||
/// communication with the supervising application. It also sets up a listener for
|
||||
/// incoming messages from the supervisor.
|
||||
ApplicationIsolateServer(
|
||||
Type channelType,
|
||||
ApplicationOptions configuration,
|
||||
|
|
@ -63,40 +26,9 @@ class ApplicationIsolateServer extends ApplicationServer {
|
|||
supervisingApplicationPort.send(supervisingReceivePort.sendPort);
|
||||
}
|
||||
|
||||
/// A SendPort used for communication with the supervising application.
|
||||
///
|
||||
/// This SendPort allows the ApplicationIsolateServer to send messages and events
|
||||
/// back to the supervising application, enabling bidirectional communication
|
||||
/// between the isolated server and its parent process.
|
||||
SendPort supervisingApplicationPort;
|
||||
|
||||
/// A ReceivePort for receiving messages from the supervising application.
|
||||
///
|
||||
/// This ReceivePort is used to listen for incoming messages from the supervising
|
||||
/// application. It's initialized in the constructor and is used to set up a
|
||||
/// listener for handling various commands and messages, such as stop requests
|
||||
/// or application events.
|
||||
///
|
||||
/// The 'late' keyword indicates that this variable will be initialized after
|
||||
/// the constructor body, but before it's used.
|
||||
late ReceivePort supervisingReceivePort;
|
||||
|
||||
/// Starts the ApplicationIsolateServer.
|
||||
///
|
||||
/// This method overrides the base class's start method to add functionality
|
||||
/// specific to the isolated server. It performs the following steps:
|
||||
/// 1. Calls the superclass's start method with the provided shareHttpServer parameter.
|
||||
/// 2. Logs a fine-level message indicating that the server has started.
|
||||
/// 3. Sends a 'listening' message to the supervising application.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - shareHttpServer: A boolean indicating whether to share the HTTP server (default is false).
|
||||
///
|
||||
/// Returns:
|
||||
/// A Future that completes with the result of the superclass's start method.
|
||||
///
|
||||
/// Throws:
|
||||
/// Any exceptions that may be thrown by the superclass's start method.
|
||||
@override
|
||||
Future start({bool shareHttpServer = false}) async {
|
||||
final result = await super.start(shareHttpServer: shareHttpServer);
|
||||
|
|
@ -109,21 +41,6 @@ class ApplicationIsolateServer extends ApplicationServer {
|
|||
return result;
|
||||
}
|
||||
|
||||
/// Sends an application event to the supervising application.
|
||||
///
|
||||
/// This method overrides the base class's sendApplicationEvent method to
|
||||
/// implement event sending in the context of an isolated server. It wraps
|
||||
/// the event in a MessageHubMessage and sends it through the
|
||||
/// supervisingApplicationPort.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - event: The application event to be sent. Can be of any type.
|
||||
///
|
||||
/// If an error occurs during the sending process, it is caught and added
|
||||
/// to the hubSink as an error, along with the stack trace.
|
||||
///
|
||||
/// Note: This method does not throw exceptions directly; instead, it
|
||||
/// reports errors through the hubSink.
|
||||
@override
|
||||
void sendApplicationEvent(dynamic event) {
|
||||
try {
|
||||
|
|
@ -133,22 +50,6 @@ class ApplicationIsolateServer extends ApplicationServer {
|
|||
}
|
||||
}
|
||||
|
||||
/// Listener method for handling incoming messages from the supervising application.
|
||||
///
|
||||
/// This method processes two types of messages:
|
||||
/// 1. A stop message (ApplicationIsolateSupervisor.messageKeyStop):
|
||||
/// When received, it calls the stop() method to shut down the server.
|
||||
/// 2. A MessageHubMessage:
|
||||
/// When received, it adds the payload of the message to the hubSink.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - message: The incoming message. Can be either a stop command or a MessageHubMessage.
|
||||
///
|
||||
/// This method doesn't return any value but performs actions based on the message type:
|
||||
/// - For a stop message, it initiates the server shutdown process.
|
||||
/// - For a MessageHubMessage, it propagates the payload to the hubSink if it exists.
|
||||
///
|
||||
/// Note: This method assumes that hubSink is properly initialized elsewhere in the class.
|
||||
void listener(dynamic message) {
|
||||
if (message == ApplicationIsolateSupervisor.messageKeyStop) {
|
||||
stop();
|
||||
|
|
@ -157,21 +58,6 @@ class ApplicationIsolateServer extends ApplicationServer {
|
|||
}
|
||||
}
|
||||
|
||||
/// Stops the ApplicationIsolateServer and performs cleanup operations.
|
||||
///
|
||||
/// This method performs the following steps:
|
||||
/// 1. Closes the supervisingReceivePort to stop receiving messages.
|
||||
/// 2. Logs a fine-level message indicating the server is closing.
|
||||
/// 3. Calls the close() method to shut down the server.
|
||||
/// 4. Logs a fine-level message confirming the server has closed.
|
||||
/// 5. Clears all listeners from the logger.
|
||||
/// 6. Logs a fine-level message indicating it's sending a stop acknowledgement.
|
||||
/// 7. Sends a stop acknowledgement message to the supervising application.
|
||||
///
|
||||
/// Returns:
|
||||
/// A Future that completes when all stop operations are finished.
|
||||
///
|
||||
/// Note: This method is asynchronous and should be awaited when called.
|
||||
Future stop() async {
|
||||
supervisingReceivePort.close();
|
||||
logger.fine("ApplicationIsolateServer($identifier) closing server");
|
||||
|
|
@ -186,40 +72,10 @@ class ApplicationIsolateServer extends ApplicationServer {
|
|||
}
|
||||
}
|
||||
|
||||
/// A typedef defining the signature for an isolate entry function.
|
||||
///
|
||||
/// This function type is used to define the entry point for an isolate in the context
|
||||
/// of an ApplicationIsolateServer. It takes a single parameter of type
|
||||
/// ApplicationInitialServerMessage, which contains all the necessary information
|
||||
/// to initialize and run the server within the isolate.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - message: An ApplicationInitialServerMessage object containing configuration
|
||||
/// details, identifiers, and communication ports needed to set up the server
|
||||
/// in the isolate.
|
||||
///
|
||||
/// This typedef is typically used when spawning new isolates for server instances,
|
||||
/// allowing for a standardized way of passing initial setup information to the isolate.
|
||||
typedef IsolateEntryFunction = void Function(
|
||||
ApplicationInitialServerMessage message,
|
||||
);
|
||||
|
||||
/// Represents the initial message sent to an ApplicationIsolateServer when it's created.
|
||||
///
|
||||
/// This class encapsulates all the necessary information needed to initialize and
|
||||
/// configure an ApplicationIsolateServer within an isolate. It includes details about
|
||||
/// the stream type, configuration options, communication ports, and logging preferences.
|
||||
///
|
||||
/// Properties:
|
||||
/// - streamTypeName: The name of the stream type to be used by the server.
|
||||
/// - streamLibraryURI: The URI of the library containing the stream implementation.
|
||||
/// - configuration: ApplicationOptions object containing server configuration details.
|
||||
/// - parentMessagePort: SendPort for communicating with the parent (supervising) application.
|
||||
/// - identifier: A unique identifier for the server instance.
|
||||
/// - logToConsole: A boolean flag indicating whether to enable console logging (default is false).
|
||||
///
|
||||
/// This class is typically used when spawning a new isolate for an ApplicationIsolateServer,
|
||||
/// providing all the necessary information in a single, structured message.
|
||||
class ApplicationInitialServerMessage {
|
||||
ApplicationInitialServerMessage(
|
||||
this.streamTypeName,
|
||||
|
|
@ -238,16 +94,6 @@ class ApplicationInitialServerMessage {
|
|||
bool logToConsole = false;
|
||||
}
|
||||
|
||||
/// Represents a message that can be sent through the message hub.
|
||||
///
|
||||
/// This class encapsulates a payload of any type, allowing for flexible
|
||||
/// communication between different parts of the application.
|
||||
///
|
||||
/// The payload can be of any type (dynamic), making this class versatile
|
||||
/// for various types of messages.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - payload: The content of the message, which can be of any type.
|
||||
class MessageHubMessage {
|
||||
MessageHubMessage(this.payload);
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:isolate';
|
||||
|
||||
|
|
@ -15,26 +6,9 @@ import 'package:logging/logging.dart';
|
|||
|
||||
/// Represents the supervision of a [ApplicationIsolateServer].
|
||||
///
|
||||
/// This class, ApplicationIsolateSupervisor, is responsible for supervising and managing
|
||||
/// an [ApplicationIsolateServer]. It handles the lifecycle of the isolate, including
|
||||
/// starting, stopping, and communicating with it. The supervisor also manages error
|
||||
/// handling, message passing between isolates, and ensures proper startup and shutdown
|
||||
/// of the supervised isolate.
|
||||
///
|
||||
/// You should not use this class directly.
|
||||
class ApplicationIsolateSupervisor {
|
||||
/// Creates an instance of [ApplicationIsolateSupervisor].
|
||||
///
|
||||
/// This constructor initializes a new [ApplicationIsolateSupervisor] with the provided parameters.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [supervisingApplication]: The [Application] instance that owns this supervisor.
|
||||
/// - [isolate]: The [Isolate] being supervised.
|
||||
/// - [receivePort]: The [ReceivePort] for receiving messages from the supervised isolate.
|
||||
/// - [identifier]: A numeric identifier for the isolate relative to the [Application].
|
||||
/// - [logger]: The [Logger] instance used for logging.
|
||||
/// - [startupTimeout]: Optional. The maximum duration to wait for the isolate to start up.
|
||||
/// Defaults to 30 seconds.
|
||||
/// Create an instance of [ApplicationIsolateSupervisor].
|
||||
ApplicationIsolateSupervisor(
|
||||
this.supervisingApplication,
|
||||
this.isolate,
|
||||
|
|
@ -44,168 +18,34 @@ class ApplicationIsolateSupervisor {
|
|||
this.startupTimeout = const Duration(seconds: 30),
|
||||
});
|
||||
|
||||
/// The [Isolate] being supervised by this [ApplicationIsolateSupervisor].
|
||||
///
|
||||
/// This isolate represents a separate thread of execution where the
|
||||
/// [ApplicationIsolateServer] runs. The supervisor manages the lifecycle
|
||||
/// and communication with this isolate.
|
||||
/// The [Isolate] being supervised.
|
||||
final Isolate isolate;
|
||||
|
||||
/// The [ReceivePort] for receiving messages from the supervised isolate.
|
||||
///
|
||||
/// This [ReceivePort] is used to establish a communication channel between
|
||||
/// the supervisor and the supervised isolate. It allows the supervisor to
|
||||
/// receive various types of messages, including startup notifications,
|
||||
/// error reports, and custom messages from the isolate.
|
||||
///
|
||||
/// The [receivePort] is crucial for managing the lifecycle of the isolate
|
||||
/// and handling inter-isolate communication. It is used in conjunction with
|
||||
/// the [listener] method to process incoming messages from the isolate.
|
||||
/// The [ReceivePort] for which messages coming from [isolate] will be received.
|
||||
final ReceivePort receivePort;
|
||||
|
||||
/// A numeric identifier for the isolate relative to the [Application].
|
||||
///
|
||||
/// This identifier is unique within the context of the parent [Application].
|
||||
/// It is used to distinguish between different isolates managed by the same
|
||||
/// application, facilitating logging, debugging, and isolate management.
|
||||
/// The identifier is typically assigned sequentially when creating new isolates.
|
||||
final int identifier;
|
||||
|
||||
/// The maximum duration to wait for the isolate to start up.
|
||||
///
|
||||
/// This duration specifies the time limit for the supervised isolate to complete its
|
||||
/// startup process. If the isolate fails to start within this timeout period, an
|
||||
/// exception will be thrown. This helps prevent indefinite waiting in case of startup
|
||||
/// issues.
|
||||
///
|
||||
/// The default value is typically set in the constructor, often to 30 seconds.
|
||||
final Duration startupTimeout;
|
||||
|
||||
/// A reference to the owning [Application].
|
||||
///
|
||||
/// This property holds a reference to the [Application] instance that owns and manages
|
||||
/// this [ApplicationIsolateSupervisor]. It allows the supervisor to interact with
|
||||
/// the main application, access shared resources, and coordinate activities across
|
||||
/// multiple isolates.
|
||||
///
|
||||
/// The supervising application is responsible for creating and managing the lifecycle
|
||||
/// of this supervisor and its associated isolate. It also provides context for
|
||||
/// operations such as logging, configuration, and inter-isolate communication.
|
||||
/// A reference to the owning [Application]
|
||||
Application supervisingApplication;
|
||||
|
||||
/// The logger instance used for recording events and errors.
|
||||
///
|
||||
/// This [Logger] is typically shared with the [supervisingApplication] and is used
|
||||
/// to log various events, warnings, and errors related to the isolate supervision
|
||||
/// process. It helps in debugging and monitoring the behavior of the supervised
|
||||
/// isolate and the supervisor itself.
|
||||
///
|
||||
/// The logger can be used to record information at different severity levels,
|
||||
/// such as fine, info, warning, and severe, depending on the nature of the event
|
||||
/// being logged.
|
||||
/// A reference to the [Logger] used by the [supervisingApplication].
|
||||
Logger logger;
|
||||
|
||||
/// A list to store pending [MessageHubMessage] objects.
|
||||
///
|
||||
/// This queue is used to temporarily hold messages that are received when the
|
||||
/// supervising application is not running. Once the application starts running,
|
||||
/// these messages are processed and sent to other supervisors.
|
||||
///
|
||||
/// The queue helps ensure that no messages are lost during the startup phase
|
||||
/// of the application, maintaining message integrity across isolates.
|
||||
final List<MessageHubMessage> _pendingMessageQueue = [];
|
||||
|
||||
/// Indicates whether the isolate is currently in the process of launching.
|
||||
///
|
||||
/// This getter returns `true` if the isolate is still in the startup phase,
|
||||
/// and `false` if the launch process has completed.
|
||||
///
|
||||
/// It checks the state of the [_launchCompleter] to determine if the
|
||||
/// launch process is still ongoing. If the completer is not yet completed,
|
||||
/// it means the isolate is still launching.
|
||||
///
|
||||
/// This property is useful for handling different behaviors or error states
|
||||
/// depending on whether the isolate is in its launch phase or has already
|
||||
/// started running normally.
|
||||
bool get _isLaunching => !_launchCompleter.isCompleted;
|
||||
|
||||
/// The [SendPort] used to send messages to the supervised isolate.
|
||||
///
|
||||
/// This [SendPort] is initialized when the supervisor receives the corresponding
|
||||
/// [SendPort] from the supervised isolate during the startup process. It enables
|
||||
/// bi-directional communication between the supervisor and the supervised isolate.
|
||||
///
|
||||
/// The [_serverSendPort] is used to send various messages to the isolate, including
|
||||
/// stop signals, custom application messages, and other control commands. It plays
|
||||
/// a crucial role in managing the lifecycle and behavior of the supervised isolate.
|
||||
late SendPort _serverSendPort;
|
||||
|
||||
/// A [Completer] used to manage the launch process of the supervised isolate.
|
||||
///
|
||||
/// This completer is initialized when the isolate is being launched and is completed
|
||||
/// when the isolate has successfully started up. It's used in conjunction with
|
||||
/// [resume] method to handle the asynchronous nature of isolate startup.
|
||||
///
|
||||
/// The completer allows other parts of the supervisor to wait for the isolate
|
||||
/// to finish launching before proceeding with further operations. It's also used
|
||||
/// to implement timeout functionality in case the isolate fails to start within
|
||||
/// the specified [startupTimeout].
|
||||
late Completer _launchCompleter;
|
||||
|
||||
/// A [Completer] used to manage the stop process of the supervised isolate.
|
||||
///
|
||||
/// This nullable [Completer] is initialized when the [stop] method is called
|
||||
/// and is used to handle the asynchronous nature of stopping the isolate.
|
||||
/// It allows the supervisor to wait for the isolate to acknowledge the stop
|
||||
/// message before proceeding with the termination process.
|
||||
///
|
||||
/// The completer is set to null after the stop process is complete, indicating
|
||||
/// that the isolate has been successfully stopped. This helps manage the state
|
||||
/// of the stop operation and prevents multiple stop attempts from interfering
|
||||
/// with each other.
|
||||
Completer? _stopCompleter;
|
||||
|
||||
/// A constant string used as a message key to signal the supervised isolate to stop.
|
||||
///
|
||||
/// This constant is used in the communication protocol between the supervisor
|
||||
/// and the supervised isolate. When sent to the isolate, it indicates that
|
||||
/// the isolate should begin its shutdown process.
|
||||
///
|
||||
/// The underscore prefix in the value suggests that this is intended for
|
||||
/// internal use within the isolate communication system.
|
||||
static const String messageKeyStop = "_MessageStop";
|
||||
|
||||
/// A constant string used as a message key to indicate that the supervised isolate is listening.
|
||||
///
|
||||
/// This constant is part of the communication protocol between the supervisor
|
||||
/// and the supervised isolate. When the isolate sends this message to the
|
||||
/// supervisor, it signals that the isolate has completed its startup process
|
||||
/// and is ready to receive and process messages.
|
||||
///
|
||||
/// The underscore prefix in the value suggests that this is intended for
|
||||
/// internal use within the isolate communication system.
|
||||
static const String messageKeyListening = "_MessageListening";
|
||||
|
||||
/// Resumes the [Isolate] being supervised.
|
||||
///
|
||||
/// This method initiates the process of resuming the supervised isolate and
|
||||
/// sets up the necessary listeners and error handlers. It performs the following steps:
|
||||
///
|
||||
/// 1. Initializes a new [Completer] for managing the launch process.
|
||||
/// 2. Sets up a listener for the [receivePort] to handle incoming messages.
|
||||
/// 3. Configures the isolate to handle errors non-fatally.
|
||||
/// 4. Adds an error listener to the isolate.
|
||||
/// 5. Resumes the isolate from its paused state.
|
||||
/// 6. Waits for the isolate to complete its startup process.
|
||||
///
|
||||
/// If the isolate fails to start within the specified [startupTimeout], a
|
||||
/// [TimeoutException] is thrown with a detailed error message.
|
||||
///
|
||||
/// Returns a [Future] that completes when the isolate has successfully started,
|
||||
/// or throws an exception if the startup process fails or times out.
|
||||
///
|
||||
/// Throws:
|
||||
/// - [TimeoutException] if the isolate doesn't start within the [startupTimeout].
|
||||
Future resume() {
|
||||
_launchCompleter = Completer();
|
||||
receivePort.listen(listener);
|
||||
|
|
@ -231,24 +71,6 @@ class ApplicationIsolateSupervisor {
|
|||
}
|
||||
|
||||
/// Stops the [Isolate] being supervised.
|
||||
///
|
||||
/// This method initiates the process of stopping the supervised isolate. It performs the following steps:
|
||||
///
|
||||
/// 1. Creates a new [Completer] to manage the stop process.
|
||||
/// 2. Sends a stop message to the supervised isolate using [_serverSendPort].
|
||||
/// 3. Waits for the isolate to acknowledge the stop message.
|
||||
/// 4. If the isolate doesn't respond within 5 seconds, logs a severe message.
|
||||
/// 5. Forcefully kills the isolate using [isolate.kill()].
|
||||
/// 6. Closes the [receivePort] to clean up resources.
|
||||
///
|
||||
/// The method uses a timeout of 5 seconds to wait for the isolate's acknowledgment.
|
||||
/// If the timeout occurs, it assumes the isolate is not responding and proceeds to terminate it.
|
||||
///
|
||||
/// This method ensures that the isolate is stopped one way or another, either gracefully
|
||||
/// or by force, and properly cleans up associated resources.
|
||||
///
|
||||
/// Returns a [Future] that completes when the stop process is finished, regardless of
|
||||
/// whether the isolate responded to the stop message or was forcefully terminated.
|
||||
Future stop() async {
|
||||
_stopCompleter = Completer();
|
||||
logger.fine(
|
||||
|
|
@ -269,22 +91,6 @@ class ApplicationIsolateSupervisor {
|
|||
receivePort.close();
|
||||
}
|
||||
|
||||
/// Handles incoming messages from the supervised isolate.
|
||||
///
|
||||
/// This method is the central message processing function for the supervisor.
|
||||
/// It handles various types of messages:
|
||||
///
|
||||
/// - [SendPort]: Stores the send port for communicating with the isolate.
|
||||
/// - [messageKeyListening]: Indicates the isolate has started and is listening.
|
||||
/// - [messageKeyStop]: Acknowledges that the isolate has received a stop message.
|
||||
/// - [List]: Represents an error from the isolate, which is then handled.
|
||||
/// - [MessageHubMessage]: Inter-isolate communication message.
|
||||
///
|
||||
/// For [MessageHubMessage], if the supervising application is not running,
|
||||
/// the message is queued. Otherwise, it's immediately sent to other supervisors.
|
||||
///
|
||||
/// This method is crucial for managing the lifecycle and communication of the
|
||||
/// supervised isolate, handling startup, shutdown, errors, and inter-isolate messaging.
|
||||
void listener(dynamic message) {
|
||||
if (message is SendPort) {
|
||||
_serverSendPort = message;
|
||||
|
|
@ -316,38 +122,12 @@ class ApplicationIsolateSupervisor {
|
|||
}
|
||||
}
|
||||
|
||||
/// Sends all pending messages stored in the [_pendingMessageQueue] to other supervisors.
|
||||
///
|
||||
/// This method is typically called when the supervising application starts running
|
||||
/// to process any messages that were received while the application was not active.
|
||||
/// It performs the following steps:
|
||||
///
|
||||
/// 1. Creates a copy of the [_pendingMessageQueue] to safely iterate over it.
|
||||
/// 2. Clears the original [_pendingMessageQueue].
|
||||
/// 3. Sends each message in the copied list to other supervisors using [_sendMessageToOtherSupervisors].
|
||||
///
|
||||
/// This ensures that no messages are lost during the startup phase of the application
|
||||
/// and maintains message integrity across isolates.
|
||||
void sendPendingMessages() {
|
||||
final list = List<MessageHubMessage>.from(_pendingMessageQueue);
|
||||
_pendingMessageQueue.clear();
|
||||
list.forEach(_sendMessageToOtherSupervisors);
|
||||
}
|
||||
|
||||
/// Sends a [MessageHubMessage] to all other supervisors managed by the supervising application.
|
||||
///
|
||||
/// This method is responsible for propagating messages across different isolates
|
||||
/// managed by the same application. It performs the following actions:
|
||||
///
|
||||
/// 1. Iterates through all supervisors in the supervising application.
|
||||
/// 2. Excludes the current supervisor from the recipients.
|
||||
/// 3. Sends the provided [message] to each of the other supervisors' isolates.
|
||||
///
|
||||
/// This method is crucial for maintaining communication and synchronization
|
||||
/// between different isolates within the application.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [message]: The [MessageHubMessage] to be sent to other supervisors.
|
||||
void _sendMessageToOtherSupervisors(MessageHubMessage message) {
|
||||
supervisingApplication.supervisors
|
||||
.where((sup) => sup != this)
|
||||
|
|
@ -356,25 +136,6 @@ class ApplicationIsolateSupervisor {
|
|||
});
|
||||
}
|
||||
|
||||
/// Handles exceptions thrown by the supervised isolate.
|
||||
///
|
||||
/// This method is responsible for processing and responding to exceptions
|
||||
/// that occur within the supervised isolate. It behaves differently depending
|
||||
/// on whether the isolate is still in the process of launching or not:
|
||||
///
|
||||
/// - If the isolate is launching ([_isLaunching] is true):
|
||||
/// It wraps the error in an [ApplicationStartupException] and completes
|
||||
/// the [_launchCompleter] with this error, effectively failing the launch process.
|
||||
///
|
||||
/// - If the isolate has already launched:
|
||||
/// It logs the error as a severe uncaught exception using the supervisor's logger.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [error]: The error or exception object thrown by the isolate.
|
||||
/// - [stacktrace]: The [StackTrace] associated with the error.
|
||||
///
|
||||
/// This method is crucial for maintaining the stability and error handling
|
||||
/// of the isolate, especially during its startup phase.
|
||||
void _handleIsolateException(dynamic error, StackTrace stacktrace) {
|
||||
if (_isLaunching) {
|
||||
final appException = ApplicationStartupException(error);
|
||||
|
|
|
|||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:io';
|
||||
|
||||
import 'package:args/args.dart';
|
||||
|
|
@ -14,73 +5,45 @@ import 'package:protevus_application/application.dart';
|
|||
|
||||
/// An object that contains configuration values for an [Application].
|
||||
///
|
||||
/// This class provides a set of options that can be used to configure an application,
|
||||
/// including network settings, SSL configuration, and custom context values.
|
||||
/// It also includes a static [ArgParser] for parsing command-line arguments.
|
||||
///
|
||||
/// Key features:
|
||||
/// - Configurable address and port for HTTP requests
|
||||
/// - IPv6 support
|
||||
/// - SSL/HTTPS configuration options
|
||||
/// - Client-side certificate usage flag
|
||||
/// - Custom context for application-specific configuration
|
||||
/// - Command-line argument parsing for easy configuration
|
||||
///
|
||||
/// Usage:
|
||||
/// This class is typically used in conjunction with [ApplicationChannel] to set up
|
||||
/// and configure an application based on external inputs or command-line arguments.
|
||||
/// You use this object in an [ApplicationChannel] to manage external configuration data for your application.
|
||||
class ApplicationOptions {
|
||||
/// The absolute path of the configuration file for this application.
|
||||
///
|
||||
/// This property stores the file path of the configuration file used by the application.
|
||||
/// The path is typically set when the application is started using the `--config-path` option
|
||||
/// with the `conduit serve` command.
|
||||
///
|
||||
/// The configuration file can contain application-specific settings and can be loaded
|
||||
/// in the [ApplicationChannel] to access these configuration values.
|
||||
///
|
||||
/// This property may be null if no configuration file path was specified when starting the application.
|
||||
///
|
||||
/// Usage:
|
||||
/// - Access this property to get the path of the configuration file.
|
||||
/// - Use the path to load and parse the configuration file in your application logic.
|
||||
/// - Ensure to handle cases where this property might be null.
|
||||
/// This path is provided when an application is started by the `--config-path` option to `conduit serve`.
|
||||
/// You may load the file at this path in [ApplicationChannel] to use configuration values.
|
||||
String? configurationFilePath;
|
||||
|
||||
/// The address to listen for HTTP requests on.
|
||||
///
|
||||
/// This property specifies the network address on which the application will listen for incoming HTTP requests.
|
||||
/// By default, this address will default to 'any' address (0.0.0.0). If [isIpv6Only] is true,
|
||||
/// 'any' will be any IPv6 address, otherwise, it will be any IPv4 or IPv6 address.
|
||||
///
|
||||
/// This value may be an [InternetAddress] or a [String].
|
||||
dynamic address;
|
||||
|
||||
/// The port number on which the application will listen for HTTP requests.
|
||||
/// The port to listen for HTTP requests on.
|
||||
///
|
||||
/// Defaults to 8888.
|
||||
int port = 8888;
|
||||
|
||||
/// Whether or not the application should only receive connections over IPv6.
|
||||
///
|
||||
/// This flag determines if the application should exclusively use IPv6 for incoming connections.
|
||||
/// When set to true, the application will only accept IPv6 connections and reject IPv4 connections.
|
||||
/// This setting can be useful in environments that require IPv6-only communication.
|
||||
///
|
||||
/// Defaults to false. This flag impacts the default value of the [address] property.
|
||||
bool isIpv6Only = false;
|
||||
|
||||
/// Indicates whether the application's request controllers should use client-side HTTPS certificates.
|
||||
/// Whether or not the application's request controllers should use client-side HTTPS certificates.
|
||||
///
|
||||
/// Defaults to false.
|
||||
bool isUsingClientCertificate = false;
|
||||
|
||||
/// The path to a SSL certificate file.
|
||||
/// The path to a SSL certificate.
|
||||
///
|
||||
/// If specified - along with [privateKeyFilePath] - an [Application] will only allow secure connections over HTTPS.
|
||||
/// This value is often set through the `--ssl-certificate-path` command line option of `conduit serve`. For finer control
|
||||
/// over how HTTPS is configured for an application, see [ApplicationChannel.securityContext].
|
||||
String? certificateFilePath;
|
||||
|
||||
/// The path to a private key file for SSL/TLS encryption.
|
||||
/// The path to a private key.
|
||||
///
|
||||
/// If specified - along with [certificateFilePath] - an [Application] will only allow secure connections over HTTPS.
|
||||
/// This value is often set through the `--ssl-key-path` command line option of `conduit serve`. For finer control
|
||||
|
|
@ -91,40 +54,8 @@ class ApplicationOptions {
|
|||
///
|
||||
/// This is a user-specific set of configuration options provided by [ApplicationChannel.initializeApplication].
|
||||
/// Each instance of [ApplicationChannel] has access to these values if set.
|
||||
///
|
||||
/// This map allows for storing and retrieving custom configuration values that can be used
|
||||
/// throughout the application. It provides a flexible way to pass application-specific
|
||||
/// settings to different parts of the system.
|
||||
///
|
||||
/// The context can be populated during the application's initialization phase and
|
||||
/// can contain any type of data that adheres to the dynamic type.
|
||||
///
|
||||
/// Usage:
|
||||
/// - Add configuration values: `context['databaseUrl'] = 'postgres://...';`
|
||||
/// - Retrieve values: `final dbUrl = options.context['databaseUrl'];`
|
||||
///
|
||||
/// Note: It's important to ensure type safety when retrieving values from this map,
|
||||
/// as it uses dynamic typing.
|
||||
final Map<String, dynamic> context = {};
|
||||
|
||||
/// A static [ArgParser] for parsing command-line arguments for the application.
|
||||
///
|
||||
/// This parser defines several options and flags that can be used to configure
|
||||
/// the application when it is launched from the command line. The available
|
||||
/// options include:
|
||||
///
|
||||
/// - address: The address to listen on for HTTP requests.
|
||||
/// - config-path: The path to a configuration file.
|
||||
/// - isolates: Number of isolates for handling requests.
|
||||
/// - port: The port number to listen for HTTP requests on.
|
||||
/// - ipv6-only: Flag to limit listening to IPv6 connections only.
|
||||
/// - ssl-certificate-path: The path to an SSL certificate file.
|
||||
/// - ssl-key-path: The path to an SSL private key file.
|
||||
/// - timeout: Number of seconds to wait to ensure startup succeeded.
|
||||
/// - help: Flag to display help information.
|
||||
///
|
||||
/// Each option is configured with a description, and some include default values
|
||||
/// or abbreviations for easier command-line usage.
|
||||
static final parser = ArgParser()
|
||||
..addOption(
|
||||
"address",
|
||||
|
|
|
|||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:isolate';
|
||||
|
||||
|
|
@ -16,21 +7,6 @@ import 'package:protevus_application/application.dart';
|
|||
Warning: do not remove. This method is invoked by a generated script.
|
||||
|
||||
*/
|
||||
|
||||
/// Starts the application either on the current isolate or across multiple isolates.
|
||||
///
|
||||
/// This function initializes and starts the application, setting up communication
|
||||
/// between isolates using ports. It responds to stop commands and reports the
|
||||
/// application's status back to the parent isolate.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - app: The Application instance to be started.
|
||||
/// - isolateCount: The number of isolates to start the application on. If 0, starts on the current isolate.
|
||||
/// - parentPort: The SendPort of the parent isolate for communication.
|
||||
///
|
||||
/// The function sets up a ReceivePort to listen for commands, particularly the "stop" command.
|
||||
/// It then starts the application either on the current isolate or across multiple isolates
|
||||
/// based on the isolateCount parameter. Finally, it sends a status message back to the parent isolate.
|
||||
Future startApplication<T extends ApplicationChannel>(
|
||||
Application<T> app,
|
||||
int isolateCount,
|
||||
|
|
|
|||
|
|
@ -7,10 +7,9 @@
|
|||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'package:protevus_auth/auth.dart';
|
||||
import 'package:protevus_hashing/hashing.dart';
|
||||
import 'package:crypto/crypto.dart';
|
||||
library;
|
||||
|
||||
export 'src/auth.dart';
|
||||
export 'src/auth_code_controller.dart';
|
||||
export 'src/auth_controller.dart';
|
||||
export 'src/auth_redirect_controller.dart';
|
||||
|
|
@ -21,60 +20,3 @@ export 'src/exceptions.dart';
|
|||
export 'src/objects.dart';
|
||||
export 'src/protocols.dart';
|
||||
export 'src/validator.dart';
|
||||
|
||||
/// A utility method to generate a password hash using the PBKDF2 scheme.
|
||||
///
|
||||
/// This function takes a password and salt as input and generates a secure hash
|
||||
/// using the PBKDF2 (Password-Based Key Derivation Function 2) algorithm.
|
||||
String generatePasswordHash(
|
||||
String password,
|
||||
String salt, {
|
||||
int hashRounds = 1000,
|
||||
int hashLength = 32,
|
||||
Hash? hashFunction,
|
||||
}) {
|
||||
final generator = PBKDF2(hashAlgorithm: hashFunction ?? sha256);
|
||||
return generator.generateBase64Key(password, salt, hashRounds, hashLength);
|
||||
}
|
||||
|
||||
/// A utility method to generate a random base64 salt.
|
||||
///
|
||||
/// This function generates a random salt encoded as a base64 string.
|
||||
/// The salt is useful for adding randomness to password hashing processes,
|
||||
/// making them more resistant to attacks.
|
||||
String generateRandomSalt({int hashLength = 32}) {
|
||||
return generateAsBase64String(hashLength);
|
||||
}
|
||||
|
||||
/// A utility method to generate a ClientID and Client Secret Pair.
|
||||
///
|
||||
/// This function creates an [AuthClient] instance, which can be either public or confidential,
|
||||
/// depending on whether a secret is provided.
|
||||
///
|
||||
/// Any client that allows the authorization code flow must include [redirectURI].
|
||||
///
|
||||
/// Note that [secret] is hashed with a randomly generated salt, and therefore cannot be retrieved
|
||||
/// later. The plain-text secret must be stored securely elsewhere.
|
||||
AuthClient generateAPICredentialPair(
|
||||
String clientID,
|
||||
String? secret, {
|
||||
String? redirectURI,
|
||||
int hashLength = 32,
|
||||
int hashRounds = 1000,
|
||||
Hash? hashFunction,
|
||||
}) {
|
||||
if (secret == null) {
|
||||
return AuthClient.public(clientID, redirectURI: redirectURI);
|
||||
}
|
||||
|
||||
final salt = generateRandomSalt(hashLength: hashLength);
|
||||
final hashed = generatePasswordHash(
|
||||
secret,
|
||||
salt,
|
||||
hashRounds: hashRounds,
|
||||
hashLength: hashLength,
|
||||
hashFunction: hashFunction,
|
||||
);
|
||||
|
||||
return AuthClient.withRedirectURI(clientID, hashed, salt, redirectURI);
|
||||
}
|
||||
|
|
|
|||
70
packages/auth/lib/src/auth.dart
Normal file
70
packages/auth/lib/src/auth.dart
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
import 'package:protevus_auth/auth.dart';
|
||||
import 'package:protevus_hashing/hashing.dart';
|
||||
import 'package:crypto/crypto.dart';
|
||||
|
||||
export 'auth_code_controller.dart';
|
||||
export 'auth_controller.dart';
|
||||
export 'auth_redirect_controller.dart';
|
||||
export 'authorization_parser.dart';
|
||||
export 'authorization_server.dart';
|
||||
export 'authorizer.dart';
|
||||
export 'exceptions.dart';
|
||||
export 'objects.dart';
|
||||
export 'protocols.dart';
|
||||
export 'validator.dart';
|
||||
|
||||
/// A utility method to generate a password hash using the PBKDF2 scheme.
|
||||
///
|
||||
///
|
||||
String generatePasswordHash(
|
||||
String password,
|
||||
String salt, {
|
||||
int hashRounds = 1000,
|
||||
int hashLength = 32,
|
||||
Hash? hashFunction,
|
||||
}) {
|
||||
final generator = PBKDF2(hashAlgorithm: hashFunction ?? sha256);
|
||||
return generator.generateBase64Key(password, salt, hashRounds, hashLength);
|
||||
}
|
||||
|
||||
/// A utility method to generate a random base64 salt.
|
||||
///
|
||||
///
|
||||
String generateRandomSalt({int hashLength = 32}) {
|
||||
return generateAsBase64String(hashLength);
|
||||
}
|
||||
|
||||
/// A utility method to generate a ClientID and Client Secret Pair.
|
||||
///
|
||||
/// [secret] may be null. If secret is null, the return value is a 'public' client. Otherwise, the
|
||||
/// client is 'confidential'. Public clients must not include a client secret when sent to the
|
||||
/// authorization server. Confidential clients must include the secret in all requests. Use public clients when
|
||||
/// the source code of the client application is visible, i.e. a JavaScript browser application.
|
||||
///
|
||||
/// Any client that allows the authorization code flow must include [redirectURI].
|
||||
///
|
||||
/// Note that [secret] is hashed with a randomly generated salt, and therefore cannot be retrieved
|
||||
/// later. The plain-text secret must be stored securely elsewhere.
|
||||
AuthClient generateAPICredentialPair(
|
||||
String clientID,
|
||||
String? secret, {
|
||||
String? redirectURI,
|
||||
int hashLength = 32,
|
||||
int hashRounds = 1000,
|
||||
Hash? hashFunction,
|
||||
}) {
|
||||
if (secret == null) {
|
||||
return AuthClient.public(clientID, redirectURI: redirectURI);
|
||||
}
|
||||
|
||||
final salt = generateRandomSalt(hashLength: hashLength);
|
||||
final hashed = generatePasswordHash(
|
||||
secret,
|
||||
salt,
|
||||
hashRounds: hashRounds,
|
||||
hashLength: hashLength,
|
||||
hashFunction: hashFunction,
|
||||
);
|
||||
|
||||
return AuthClient.withRedirectURI(clientID, hashed, salt, redirectURI);
|
||||
}
|
||||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:io';
|
||||
|
||||
|
|
@ -16,20 +7,13 @@ import 'package:protevus_http/http.dart';
|
|||
import 'package:protevus_openapi/v3.dart';
|
||||
|
||||
/// Provides [AuthCodeController] with application-specific behavior.
|
||||
///
|
||||
/// This abstract class defines the interface for a delegate that can be used
|
||||
/// with [AuthCodeController] to customize the rendering of the login form.
|
||||
/// It is deprecated along with [AuthCodeController], and developers are
|
||||
/// advised to see the documentation for alternative approaches.
|
||||
///
|
||||
/// The main responsibility of this delegate is to generate an HTML
|
||||
/// representation of a login form when requested by the [AuthCodeController].
|
||||
@Deprecated('AuthCodeController is deprecated. See docs.')
|
||||
abstract class AuthCodeControllerDelegate {
|
||||
/// Returns an HTML representation of a login form.
|
||||
///
|
||||
/// This method is responsible for generating the HTML content of a login form
|
||||
/// that will be displayed to the user when they attempt to authenticate.
|
||||
/// Invoked when [AuthCodeController.getAuthorizationPage] is called in response to a GET request.
|
||||
/// Must provide HTML that will be returned to the browser for rendering. This form submission of this page
|
||||
/// should be a POST to [requestUri].
|
||||
///
|
||||
/// The form submission should include the values of [responseType], [clientID], [state], [scope]
|
||||
/// as well as user-entered username and password in `x-www-form-urlencoded` data, e.g.
|
||||
|
|
@ -53,29 +37,24 @@ abstract class AuthCodeControllerDelegate {
|
|||
|
||||
/// Controller for issuing OAuth 2.0 authorization codes.
|
||||
///
|
||||
/// This controller handles the authorization code grant flow of OAuth 2.0. It provides
|
||||
/// endpoints for both initiating the flow (GET request) and completing it (POST request).
|
||||
/// Deprecated, use [AuthRedirectController] instead.
|
||||
///
|
||||
/// This controller provides an endpoint for the creating an OAuth 2.0 authorization code. This authorization code
|
||||
/// can be exchanged for an access token with an [AuthController]. This is known as the OAuth 2.0 'Authorization Code Grant' flow.
|
||||
///
|
||||
/// See operation methods [getAuthorizationPage] and [authorize] for more details.
|
||||
///
|
||||
/// Usage:
|
||||
///
|
||||
/// router
|
||||
/// .route("/auth/code")
|
||||
/// .link(() => new AuthCodeController(authServer));
|
||||
///
|
||||
@Deprecated('Use AuthRedirectController instead.')
|
||||
class AuthCodeController extends ResourceController {
|
||||
/// Creates a new instance of an [AuthCodeController].
|
||||
///
|
||||
/// This constructor initializes an [AuthCodeController] with the provided [authServer].
|
||||
/// It is marked as deprecated, and users are advised to use [AuthRedirectController] instead.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [authServer]: The required authorization server used for handling authentication.
|
||||
/// - [delegate]: An optional [AuthCodeControllerDelegate] that, if provided, allows this controller
|
||||
/// to return a login page for all GET requests.
|
||||
///
|
||||
/// The constructor also sets the [acceptedContentTypes] to only accept
|
||||
/// "application/x-www-form-urlencoded" content type.
|
||||
///
|
||||
/// This controller is part of the OAuth 2.0 authorization code flow and is used
|
||||
/// for issuing authorization codes. However, due to its deprecated status,
|
||||
/// it's recommended to transition to newer alternatives as specified in the documentation.
|
||||
/// [authServer] is the required authorization server. If [delegate] is provided, this controller will return a login page for all GET requests.
|
||||
@Deprecated('Use AuthRedirectController instead.')
|
||||
AuthCodeController(this.authServer, {this.delegate}) {
|
||||
acceptedContentTypes = [
|
||||
|
|
@ -84,11 +63,6 @@ class AuthCodeController extends ResourceController {
|
|||
}
|
||||
|
||||
/// A reference to the [AuthServer] used to grant authorization codes.
|
||||
///
|
||||
/// This [AuthServer] instance is responsible for handling the authentication
|
||||
/// and authorization processes, including the generation and validation of
|
||||
/// authorization codes. It is a crucial component of the OAuth 2.0 flow
|
||||
/// implemented by this controller.
|
||||
final AuthServer authServer;
|
||||
|
||||
/// A randomly generated value the client can use to verify the origin of the redirect.
|
||||
|
|
@ -96,53 +70,23 @@ class AuthCodeController extends ResourceController {
|
|||
/// Clients must include this query parameter and verify that any redirects from this
|
||||
/// server have the same value for 'state' as passed in. This value is usually a randomly generated
|
||||
/// session identifier.
|
||||
///
|
||||
/// This property is bound to the 'state' query parameter in the request URL.
|
||||
/// It plays a crucial role in preventing cross-site request forgery (CSRF) attacks
|
||||
/// by ensuring that the authorization request and response originate from the same client session.
|
||||
///
|
||||
/// The 'state' parameter should be:
|
||||
/// - Unique for each authorization request
|
||||
/// - Securely generated to be unguessable
|
||||
/// - Stored by the client for later comparison
|
||||
///
|
||||
/// When the authorization server redirects the user back to the client,
|
||||
/// it includes this state value, allowing the client to verify that the redirect
|
||||
/// is in response to its own authorization request.
|
||||
@Bind.query("state")
|
||||
String? state;
|
||||
|
||||
/// The type of response expected from the authorization server.
|
||||
///
|
||||
/// This parameter is bound to the 'response_type' query parameter in the request URL.
|
||||
/// For the authorization code flow, this value must be 'code'.
|
||||
///
|
||||
/// The response type indicates to the authorization server which grant type
|
||||
/// is being utilized. In this case, 'code' signifies that the client expects
|
||||
/// to receive an authorization code that can be exchanged for an access token
|
||||
/// in a subsequent request.
|
||||
///
|
||||
/// Must be 'code'.
|
||||
@Bind.query("response_type")
|
||||
String? responseType;
|
||||
|
||||
/// The client ID of the authenticating client.
|
||||
///
|
||||
/// This property is bound to the 'client_id' query parameter in the request URL.
|
||||
/// It represents the unique identifier of the client application requesting authorization.
|
||||
///
|
||||
/// The client ID must be registered and valid according to the [authServer].
|
||||
/// It is used to identify the client during the OAuth 2.0 authorization process.
|
||||
///
|
||||
/// This field is nullable, but typically required for most OAuth 2.0 flows.
|
||||
/// If not provided or invalid, the authorization request may be rejected.
|
||||
/// This must be a valid client ID according to [authServer].\
|
||||
@Bind.query("client_id")
|
||||
String? clientID;
|
||||
|
||||
/// Renders an HTML login form.
|
||||
final AuthCodeControllerDelegate? delegate;
|
||||
|
||||
/// Returns an HTML login form for OAuth 2.0 authorization.
|
||||
/// Returns an HTML login form.
|
||||
///
|
||||
/// A client that wishes to authenticate with this server should direct the user
|
||||
/// to this page. The user will enter their username and password that is sent as a POST
|
||||
|
|
@ -171,61 +115,20 @@ class AuthCodeController extends ResourceController {
|
|||
|
||||
/// Creates a one-time use authorization code.
|
||||
///
|
||||
/// This method handles the POST request for the OAuth 2.0 authorization code grant flow.
|
||||
/// It authenticates the user with the provided credentials and, if successful, generates
|
||||
/// a one-time use authorization code.
|
||||
/// This method will respond with a redirect that contains an authorization code ('code')
|
||||
/// and the passed in 'state'. If this request fails, the redirect URL
|
||||
/// will contain an 'error' key instead of the authorization code.
|
||||
///
|
||||
/// This method is typically invoked by the login form returned from the GET to this controller.
|
||||
@Operation.post()
|
||||
Future<Response> authorize({
|
||||
/// The username of the authenticating user.
|
||||
///
|
||||
/// This parameter is bound to the 'username' query parameter in the request URL.
|
||||
/// It represents the username of the user attempting to authenticate.
|
||||
///
|
||||
/// The username is used in conjunction with the password to verify the user's identity
|
||||
/// during the OAuth 2.0 authorization code grant flow. It is a crucial part of the
|
||||
/// user authentication process.
|
||||
///
|
||||
/// This field is nullable, but typically required for successful authentication.
|
||||
/// If not provided or invalid, the authorization request may be rejected.
|
||||
@Bind.query("username") String? username,
|
||||
|
||||
/// The password of the authenticating user.
|
||||
///
|
||||
/// This parameter is bound to the 'password' query parameter in the request URL.
|
||||
/// It represents the password of the user attempting to authenticate.
|
||||
///
|
||||
/// The password is used in conjunction with the username to verify the user's identity
|
||||
/// during the OAuth 2.0 authorization code grant flow. It is a crucial part of the
|
||||
/// user authentication process.
|
||||
///
|
||||
/// This field is nullable, but typically required for successful authentication.
|
||||
/// If not provided or invalid, the authorization request may be rejected.
|
||||
///
|
||||
/// Note: Transmitting passwords as query parameters is not recommended for production
|
||||
/// environments due to security concerns. This approach should only be used in
|
||||
/// controlled, secure environments or for testing purposes.
|
||||
@Bind.query("password") String? password,
|
||||
|
||||
/// A space-delimited list of access scopes being requested.
|
||||
///
|
||||
/// This parameter is bound to the 'scope' query parameter in the request URL.
|
||||
/// It represents the permissions that the client is requesting access to.
|
||||
///
|
||||
/// The scope is typically a string containing one or more space-separated
|
||||
/// scope values. Each scope value represents a specific permission or
|
||||
/// set of permissions that the client is requesting.
|
||||
///
|
||||
/// For example, a scope might look like: "read_profile edit_profile"
|
||||
///
|
||||
/// The authorization server can use this information to present
|
||||
/// the user with a consent screen, allowing them to approve or deny
|
||||
/// specific permissions requested by the client.
|
||||
///
|
||||
/// This field is optional. If not provided, the authorization server
|
||||
/// may assign a default set of scopes or handle the request according
|
||||
/// to its own policies.
|
||||
@Bind.query("scope") String? scope,
|
||||
}) async {
|
||||
final client = await authServer.getClient(clientID!);
|
||||
|
|
@ -271,25 +174,6 @@ class AuthCodeController extends ResourceController {
|
|||
}
|
||||
}
|
||||
|
||||
/// Overrides the default documentation for the request body of this controller's operations.
|
||||
///
|
||||
/// This method is called during the OpenAPI documentation generation process.
|
||||
/// It modifies the request body schema for POST operations to:
|
||||
/// 1. Set the format of the 'password' field to "password".
|
||||
/// 2. Mark certain fields as required in the request body.
|
||||
///
|
||||
/// The method specifically targets the "application/x-www-form-urlencoded" content type
|
||||
/// in POST requests. It updates the schema to indicate that the 'password' field should
|
||||
/// be treated as a password input, and sets the following fields as required:
|
||||
/// - client_id
|
||||
/// - state
|
||||
/// - response_type
|
||||
/// - username
|
||||
/// - password
|
||||
///
|
||||
/// Returns:
|
||||
/// An [APIRequestBody] object representing the documented request body,
|
||||
/// or null if there is no request body for the operation.
|
||||
@override
|
||||
APIRequestBody? documentOperationRequestBody(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -310,20 +194,6 @@ class AuthCodeController extends ResourceController {
|
|||
return body;
|
||||
}
|
||||
|
||||
/// Overrides the default documentation for operation parameters.
|
||||
///
|
||||
/// This method is called during the OpenAPI documentation generation process.
|
||||
/// It modifies the parameter documentation for the controller's operations by:
|
||||
/// 1. Retrieving the default parameters using the superclass method.
|
||||
/// 2. Setting all parameters except 'scope' as required.
|
||||
///
|
||||
/// Parameters:
|
||||
/// context: The [APIDocumentContext] for the current documentation generation.
|
||||
/// operation: The [Operation] being documented.
|
||||
///
|
||||
/// Returns:
|
||||
/// A List of [APIParameter] objects representing the documented parameters,
|
||||
/// with updated 'isRequired' properties.
|
||||
@override
|
||||
List<APIParameter> documentOperationParameters(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -336,28 +206,6 @@ class AuthCodeController extends ResourceController {
|
|||
return params;
|
||||
}
|
||||
|
||||
/// Generates documentation for the operation responses of this controller.
|
||||
///
|
||||
/// This method overrides the default behavior to provide custom documentation
|
||||
/// for the GET and POST operations of the AuthCodeController.
|
||||
///
|
||||
/// For GET requests:
|
||||
/// - Defines a 200 OK response that serves a login form in HTML format.
|
||||
///
|
||||
/// For POST requests:
|
||||
/// - Defines a 302 Found (Moved Temporarily) response for successful requests,
|
||||
/// indicating that the 'code' query parameter in the redirect URI contains
|
||||
/// the authorization code, or an 'error' parameter is present for errors.
|
||||
/// - Defines a 400 Bad Request response for cases where the 'client_id' is
|
||||
/// invalid and the redirect URI cannot be verified.
|
||||
///
|
||||
/// Parameters:
|
||||
/// context: The API documentation context.
|
||||
/// operation: The operation being documented.
|
||||
///
|
||||
/// Returns:
|
||||
/// A Map of status codes to APIResponse objects describing the possible
|
||||
/// responses for the operation.
|
||||
@override
|
||||
Map<String, APIResponse> documentOperationResponses(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -392,24 +240,6 @@ class AuthCodeController extends ResourceController {
|
|||
throw StateError("AuthCodeController documentation failed.");
|
||||
}
|
||||
|
||||
/// Customizes the documentation for the operations of this controller.
|
||||
///
|
||||
/// This method overrides the default implementation to add additional
|
||||
/// information specific to the OAuth 2.0 authorization code flow.
|
||||
///
|
||||
/// It performs the following tasks:
|
||||
/// 1. Calls the superclass method to get the default operation documentation.
|
||||
/// 2. Updates the authorization URL in the documented authorization code flow
|
||||
/// of the auth server to match the current route.
|
||||
///
|
||||
/// Parameters:
|
||||
/// context: The [APIDocumentContext] for the current documentation generation.
|
||||
/// route: The route string for this controller.
|
||||
/// path: The [APIPath] object representing the path in the API documentation.
|
||||
///
|
||||
/// Returns:
|
||||
/// A Map of operation names to [APIOperation] objects representing the
|
||||
/// documented operations for this controller.
|
||||
@override
|
||||
Map<String, APIOperation> documentOperations(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -422,27 +252,6 @@ class AuthCodeController extends ResourceController {
|
|||
return ops;
|
||||
}
|
||||
|
||||
/// Generates a redirect response for the OAuth 2.0 authorization code flow.
|
||||
///
|
||||
/// This method constructs a redirect URI based on the provided parameters and
|
||||
/// returns a Response object with appropriate headers for redirection.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [inputUri]: The base URI to redirect to. If null, falls back to the client's redirectURI.
|
||||
/// - [clientStateOrNull]: The state parameter provided by the client. If not null, it's included in the redirect URI.
|
||||
/// - [code]: The authorization code to be included in the redirect URI. Optional.
|
||||
/// - [error]: An AuthServerException containing error details. Optional.
|
||||
///
|
||||
/// Returns:
|
||||
/// - A Response object with status 302 (Found) and appropriate headers for redirection.
|
||||
/// - If no valid redirect URI can be constructed, returns a 400 (Bad Request) response.
|
||||
///
|
||||
/// The method constructs the redirect URI by:
|
||||
/// 1. Determining the base URI (from input or client's redirect URI)
|
||||
/// 2. Adding query parameters for code, state, and error as applicable
|
||||
/// 3. Constructing a new URI with these parameters
|
||||
///
|
||||
/// The response includes headers for location, cache control, and pragma.
|
||||
static Response _redirectResponse(
|
||||
String? inputUri,
|
||||
String? clientStateOrNull, {
|
||||
|
|
|
|||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:io';
|
||||
|
||||
|
|
@ -58,30 +49,6 @@ class AuthController extends ResourceController {
|
|||
|
||||
final AuthorizationBasicParser _parser = const AuthorizationBasicParser();
|
||||
|
||||
/// This class, AuthController, is responsible for handling OAuth 2.0 token operations.
|
||||
/// It provides functionality for issuing and refreshing access tokens using various grant types.
|
||||
///
|
||||
/// Key features:
|
||||
/// - Supports 'password', 'refresh_token', and 'authorization_code' grant types
|
||||
/// - Handles client authentication via Basic Authorization header
|
||||
/// - Processes token requests and returns RFC6749 compliant responses
|
||||
/// - Includes error handling for various authentication scenarios
|
||||
/// - Provides OpenAPI documentation support
|
||||
///
|
||||
/// The main method, 'grant', processes token requests based on the provided grant type.
|
||||
/// It interacts with an AuthServer to perform the actual authentication and token generation.
|
||||
///
|
||||
/// This controller also includes methods for generating API documentation,
|
||||
/// including operation parameters, request body, and responses.
|
||||
///
|
||||
/// Usage:
|
||||
/// router
|
||||
/// .route("/auth/token")
|
||||
/// .link(() => new AuthController(authServer));
|
||||
///
|
||||
/// Note: This controller expects client credentials to be provided in the Authorization header
|
||||
/// using the Basic authentication scheme.
|
||||
///
|
||||
/// Creates or refreshes an authentication token.
|
||||
///
|
||||
/// When grant_type is 'password', there must be username and password values.
|
||||
|
|
@ -92,88 +59,11 @@ class AuthController extends ResourceController {
|
|||
/// include a valid Client ID and Secret in the Basic authorization scheme format.
|
||||
@Operation.post()
|
||||
Future<Response> grant({
|
||||
/// The username of the user attempting to authenticate.
|
||||
///
|
||||
/// This parameter is typically used with the 'password' grant type.
|
||||
/// It should be provided as a query parameter in the request.
|
||||
@Bind.query("username") String? username,
|
||||
|
||||
/// The password of the user attempting to authenticate.
|
||||
///
|
||||
/// This parameter is typically used with the 'password' grant type.
|
||||
/// It should be provided as a query parameter in the request.
|
||||
/// Note: Sending passwords as query parameters is not recommended for production environments due to security concerns.
|
||||
@Bind.query("password") String? password,
|
||||
|
||||
/// The refresh token used to obtain a new access token.
|
||||
///
|
||||
/// This parameter is typically used with the 'refresh_token' grant type.
|
||||
/// It should be provided as a query parameter in the request.
|
||||
/// The refresh token is used to request a new access token when the current one has expired.
|
||||
///
|
||||
/// Example:
|
||||
/// curl -X POST -d "grant_type=refresh_token&refresh_token=<refresh_token>" https://example.com/auth/token
|
||||
///
|
||||
/// Note: The refresh token should be securely stored and managed by the client application.
|
||||
/// It is important to handle refresh tokens with care to prevent unauthorized access to user resources.
|
||||
///
|
||||
/// See also:
|
||||
/// - [RFC 6749, Section 6](https://tools.ietf.org/html/rfc6749#section-6) for more details on the refresh token grant type.
|
||||
/// - [OAuth 2.0 Refresh Token Grant](https://oauth.net/2/grant-types/refresh-token/) for a detailed explanation of the refresh token grant type.
|
||||
/// - [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13#section-2.1) for security considerations when implementing OAuth 2.0.
|
||||
@Bind.query("refresh_token") String? refreshToken,
|
||||
|
||||
/// The authorization code obtained from the authorization server.
|
||||
///
|
||||
/// This parameter is typically used with the 'authorization_code' grant type.
|
||||
/// It should be provided as a query parameter in the request.
|
||||
/// The authorization code is used to request an access token after the user has granted permission to the client application.
|
||||
///
|
||||
/// Example:
|
||||
/// curl -X POST -d "grant_type=authorization_code&code=<authorization_code>&redirect_uri=<redirect_uri>" https://example.com/auth/token
|
||||
///
|
||||
/// Note: The authorization code should be securely transmitted and used only once to prevent replay attacks.
|
||||
/// It is important to handle authorization codes with care to protect user data and ensure the security of the OAuth 2.0 flow.
|
||||
///
|
||||
/// See also:
|
||||
/// - [RFC 6749, Section 4.1.3](https://tools.ietf.org/html/rfc6749#section-4.1.3) for more details on the authorization code grant type.
|
||||
/// - [OAuth 2.0 Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) for a detailed explanation of the authorization code grant type.
|
||||
/// - [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13#section-2.1) for security considerations when implementing OAuth 2.0.
|
||||
@Bind.query("code") String? authCode,
|
||||
|
||||
/// The URI to which the authorization server will redirect the user-agent after obtaining authorization.
|
||||
///
|
||||
/// This parameter is typically used with the 'authorization_code' grant type.
|
||||
/// It should be provided as a query parameter in the request.
|
||||
/// The redirect URI is used to ensure that the authorization code is sent to the correct client application.
|
||||
///
|
||||
/// Example:
|
||||
/// curl -X POST -d "grant_type=authorization_code&code=<authorization_code>&redirect_uri=https://example.com/callback" https://example.com/auth/token
|
||||
///
|
||||
/// Note: The redirect URI should be registered with the authorization server and should match the URI used during the authorization request.
|
||||
/// It is important to handle redirect URIs with care to prevent unauthorized access to user resources.
|
||||
///
|
||||
/// See also:
|
||||
/// - [RFC 6749, Section 4.1.3](https://tools.ietf.org/html/rfc6749#section-4.1.3) for more details on the authorization code grant type.
|
||||
/// - [OAuth 2.0 Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) for a detailed explanation of the authorization code grant type.
|
||||
/// - [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13#section-2.1) for security considerations when implementing OAuth 2.0.
|
||||
@Bind.query("grant_type") String? grantType,
|
||||
|
||||
/// The scope of the access request, which defines the resources and permissions that the client application is requesting.
|
||||
///
|
||||
/// This parameter is optional and should be provided as a query parameter in the request.
|
||||
/// The scope value is a space-delimited list of scope identifiers, which indicate the specific resources and permissions that the client application needs to access.
|
||||
///
|
||||
/// Example:
|
||||
/// curl -X POST -d "grant_type=authorization_code&code=<authorization_code>&redirect_uri=<redirect_uri>&scope=read write" https://example.com/auth/token
|
||||
///
|
||||
/// Note: The scope parameter should be used to limit the access granted to the client application to only the necessary resources and permissions.
|
||||
/// It is important to handle scope values with care to ensure that the client application does not have unintended access to user resources.
|
||||
///
|
||||
/// See also:
|
||||
/// - [RFC 6749, Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3) for more details on the scope parameter.
|
||||
/// - [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13#section-2.2) for security considerations when implementing OAuth 2.0 scope.
|
||||
/// - [OAuth 2.0 Scope](https://oauth.net/2/scope/) for a detailed explanation of the scope parameter and its usage.
|
||||
@Bind.query("scope") String? scope,
|
||||
}) async {
|
||||
AuthBasicCredentials basicRecord;
|
||||
|
|
@ -228,28 +118,6 @@ class AuthController extends ResourceController {
|
|||
|
||||
/// Transforms a [AuthToken] into a [Response] object with an RFC6749 compliant JSON token
|
||||
/// as the HTTP response body.
|
||||
///
|
||||
/// This static method takes an [AuthToken] object and converts it into a [Response] object
|
||||
/// that adheres to the OAuth 2.0 specification (RFC6749). The response includes:
|
||||
/// - A status code of 200 (OK)
|
||||
/// - Headers to prevent caching of the token
|
||||
/// - A body containing the token information in JSON format
|
||||
///
|
||||
/// Parameters:
|
||||
/// - token: An [AuthToken] object containing the authentication token details
|
||||
///
|
||||
/// Returns:
|
||||
/// A [Response] object with the token information, ready to be sent to the client
|
||||
///
|
||||
/// Example usage:
|
||||
/// ```dart
|
||||
/// AuthToken myToken = // ... obtain token
|
||||
/// Response response = AuthController.tokenResponse(myToken);
|
||||
/// ```
|
||||
///
|
||||
/// See also:
|
||||
/// - [RFC6749](https://tools.ietf.org/html/rfc6749) for the OAuth 2.0 specification
|
||||
/// - [AuthToken] for the structure of the token object
|
||||
static Response tokenResponse(AuthToken token) {
|
||||
return Response(
|
||||
HttpStatus.ok,
|
||||
|
|
@ -258,24 +126,6 @@ class AuthController extends ResourceController {
|
|||
);
|
||||
}
|
||||
|
||||
/// Processes the response before it is sent, specifically handling duplicate parameter errors.
|
||||
///
|
||||
/// This method is called just before a response is sent. It checks for responses with a 400 status code
|
||||
/// and modifies the error message in case of duplicate parameters in the request, which violates the OAuth 2.0 specification.
|
||||
///
|
||||
/// The method performs the following actions:
|
||||
/// 1. Checks if the response status code is 400 (Bad Request).
|
||||
/// 2. If the response body contains an "error" key with a string value, it examines the error message.
|
||||
/// 3. If the error message indicates multiple values (likely due to duplicate parameters), it replaces the error message
|
||||
/// with a standard "invalid_request" error as defined in the OAuth 2.0 specification.
|
||||
///
|
||||
/// This post-processing helps to maintain compliance with the OAuth 2.0 specification by providing a standard error
|
||||
/// response for invalid requests, even in the case of duplicate parameters which are not explicitly handled elsewhere.
|
||||
///
|
||||
/// Parameters:
|
||||
/// response: The Response object that will be sent to the client.
|
||||
///
|
||||
/// Note: This method directly modifies the response object if conditions are met.
|
||||
@override
|
||||
void willSendResponse(Response response) {
|
||||
if (response.statusCode == 400) {
|
||||
|
|
@ -295,20 +145,6 @@ class AuthController extends ResourceController {
|
|||
}
|
||||
}
|
||||
|
||||
/// Modifies the list of API parameters documented for this operation.
|
||||
///
|
||||
/// This method overrides the default behavior to remove the 'Authorization' header
|
||||
/// from the list of documented parameters. This is typically done because the
|
||||
/// Authorization header is handled separately in OAuth 2.0 flows and doesn't need
|
||||
/// to be explicitly documented as an operation parameter.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - context: The current API documentation context.
|
||||
/// - operation: The operation being documented (can be null).
|
||||
///
|
||||
/// Returns:
|
||||
/// A list of [APIParameter] objects representing the documented parameters
|
||||
/// for this operation, with the Authorization header removed.
|
||||
@override
|
||||
List<APIParameter> documentOperationParameters(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -319,21 +155,6 @@ class AuthController extends ResourceController {
|
|||
return parameters;
|
||||
}
|
||||
|
||||
/// Customizes the documentation for the request body of this operation.
|
||||
///
|
||||
/// This method overrides the default behavior to add specific requirements
|
||||
/// and formatting for the OAuth 2.0 token endpoint:
|
||||
///
|
||||
/// 1. It marks the 'grant_type' parameter as required in the request body.
|
||||
/// 2. It sets the format of the 'password' field to "password", indicating
|
||||
/// that it should be treated as a sensitive input in API documentation tools.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - context: The current API documentation context.
|
||||
/// - operation: The operation being documented (can be null).
|
||||
///
|
||||
/// Returns:
|
||||
/// An [APIRequestBody] object with the customized schema for the request body.
|
||||
@override
|
||||
APIRequestBody documentOperationRequestBody(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -348,20 +169,6 @@ class AuthController extends ResourceController {
|
|||
return body;
|
||||
}
|
||||
|
||||
/// Customizes the API documentation for the operations handled by this controller.
|
||||
///
|
||||
/// This method overrides the default behavior to:
|
||||
/// 1. Add OAuth 2.0 client authentication security requirement to all operations.
|
||||
/// 2. Set the token and refresh URLs for the documented authorization code flow.
|
||||
/// 3. Set the token and refresh URLs for the documented password flow.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - context: The current API documentation context.
|
||||
/// - route: The route string for the current operations.
|
||||
/// - path: The APIPath object representing the current path.
|
||||
///
|
||||
/// Returns:
|
||||
/// A map of operation names to APIOperation objects with the customized documentation.
|
||||
@override
|
||||
Map<String, APIOperation> documentOperations(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -386,25 +193,6 @@ class AuthController extends ResourceController {
|
|||
return operations;
|
||||
}
|
||||
|
||||
/// Defines the API responses for the token operation in OpenAPI documentation.
|
||||
///
|
||||
/// This method overrides the default behavior to provide custom documentation
|
||||
/// for the responses of the token endpoint. It describes two possible responses:
|
||||
///
|
||||
/// 1. A successful response (200 OK) when credentials are successfully exchanged for a token.
|
||||
/// This response includes details about the issued token such as access_token, token_type,
|
||||
/// expiration time, refresh_token, and scope.
|
||||
///
|
||||
/// 2. An error response (400 Bad Request) for cases of invalid credentials or missing parameters.
|
||||
/// This response includes an error message.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - context: The current API documentation context.
|
||||
/// - operation: The operation being documented (can be null).
|
||||
///
|
||||
/// Returns:
|
||||
/// A map of status codes to APIResponse objects describing the possible
|
||||
/// responses for this operation.
|
||||
@override
|
||||
Map<String, APIResponse> documentOperationResponses(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -430,27 +218,6 @@ class AuthController extends ResourceController {
|
|||
};
|
||||
}
|
||||
|
||||
/// Creates a Response object for an authentication error.
|
||||
///
|
||||
/// This method generates a standardized HTTP response for various authentication
|
||||
/// errors that may occur during the OAuth 2.0 flow. It uses the [AuthRequestError]
|
||||
/// enum to determine the specific error and creates a response with:
|
||||
/// - A status code of 400 (Bad Request)
|
||||
/// - A JSON body containing an "error" key with a description of the error
|
||||
///
|
||||
/// Parameters:
|
||||
/// - error: An [AuthRequestError] enum representing the specific authentication error.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [Response] object with status code 400 and a JSON body describing the error.
|
||||
///
|
||||
/// Example usage:
|
||||
/// ```dart
|
||||
/// Response errorResponse = _responseForError(AuthRequestError.invalidRequest);
|
||||
/// ```
|
||||
///
|
||||
/// The error string in the response body is generated using [AuthServerException.errorString],
|
||||
/// ensuring consistency with OAuth 2.0 error reporting standards.
|
||||
Response _responseForError(AuthRequestError error) {
|
||||
return Response.badRequest(
|
||||
body: {"error": AuthServerException.errorString(error)},
|
||||
|
|
|
|||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:io';
|
||||
|
||||
|
|
@ -15,31 +6,13 @@ import 'package:protevus_auth/auth.dart';
|
|||
import 'package:protevus_http/http.dart';
|
||||
import 'package:protevus_openapi/v3.dart';
|
||||
|
||||
/// Abstract class defining the interface for providing application-specific behavior to [AuthRedirectController].
|
||||
///
|
||||
/// This delegate is responsible for rendering the HTML login form when [AuthRedirectController.getAuthorizationPage]
|
||||
/// is called in response to a GET request. Implementations of this class should customize the login form
|
||||
/// according to the application's needs while ensuring that the form submission adheres to the required format.
|
||||
///
|
||||
/// The rendered form should:
|
||||
/// - Be submitted as a POST request to the [requestUri].
|
||||
/// - Include all provided parameters (responseType, clientID, state, scope) in the form submission.
|
||||
/// - Collect and include user-entered username and password.
|
||||
/// - Use 'application/x-www-form-urlencoded' as the Content-Type for form submission.
|
||||
///
|
||||
/// Example of expected form submission:
|
||||
///
|
||||
/// POST https://example.com/auth/code
|
||||
/// Content-Type: application/x-www-form-urlencoded
|
||||
///
|
||||
/// response_type=code&client_id=com.conduit.app&state=o9u3jla&username=bob&password=password
|
||||
///
|
||||
/// Implementations should take care to handle all provided parameters and ensure secure transmission of credentials.
|
||||
/// Provides [AuthRedirectController] with application-specific behavior.
|
||||
abstract class AuthRedirectControllerDelegate {
|
||||
/// Returns an HTML representation of a login form.
|
||||
///
|
||||
/// This method is responsible for generating and returning the HTML content for a login form
|
||||
/// when [AuthRedirectController.getAuthorizationPage] is called in response to a GET request.
|
||||
/// Invoked when [AuthRedirectController.getAuthorizationPage] is called in response to a GET request.
|
||||
/// Must provide HTML that will be returned to the browser for rendering. This form submission of this page
|
||||
/// should be a POST to [requestUri].
|
||||
///
|
||||
/// The form submission should include the values of [responseType], [clientID], [state], [scope]
|
||||
/// as well as user-entered username and password in `x-www-form-urlencoded` data, e.g.
|
||||
|
|
@ -78,23 +51,7 @@ abstract class AuthRedirectControllerDelegate {
|
|||
class AuthRedirectController extends ResourceController {
|
||||
/// Creates a new instance of an [AuthRedirectController].
|
||||
///
|
||||
/// This constructor initializes an [AuthRedirectController] with the provided [authServer].
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [authServer]: The required authorization server.
|
||||
/// - [delegate]: Optional. If provided, this controller will return a login page for all GET requests.
|
||||
/// - [allowsImplicit]: Optional. Defaults to true. Determines if the controller allows the Implicit Grant Flow.
|
||||
///
|
||||
/// The constructor also sets the [acceptedContentTypes] to ["application/x-www-form-urlencoded"].
|
||||
///
|
||||
/// Usage:
|
||||
/// ```dart
|
||||
/// final authRedirectController = AuthRedirectController(
|
||||
/// myAuthServer,
|
||||
/// delegate: myDelegate,
|
||||
/// allowsImplicit: false,
|
||||
/// );
|
||||
/// ```
|
||||
/// [authServer] is the required authorization server. If [delegate] is provided, this controller will return a login page for all GET requests.
|
||||
AuthRedirectController(
|
||||
this.authServer, {
|
||||
this.delegate,
|
||||
|
|
@ -105,108 +62,38 @@ class AuthRedirectController extends ResourceController {
|
|||
];
|
||||
}
|
||||
|
||||
/// A pre-defined Response object for unsupported response types.
|
||||
///
|
||||
/// This static final variable creates a Response object with:
|
||||
/// - HTTP status code 400 (Bad Request)
|
||||
/// - HTML content indicating an "unsupported_response_type" error
|
||||
/// - Content-Type set to text/html
|
||||
///
|
||||
/// This response is used when the 'response_type' parameter in the request
|
||||
/// is neither 'code' nor 'token', or when 'token' is requested but implicit
|
||||
/// grant flow is not allowed.
|
||||
static final Response _unsupportedResponseTypeResponse = Response.badRequest(
|
||||
body: "<h1>Error</h1><p>unsupported_response_type</p>",
|
||||
)..contentType = ContentType.html;
|
||||
|
||||
/// A reference to the [AuthServer] used to grant authorization codes and access tokens.
|
||||
///
|
||||
/// This property holds an instance of [AuthServer] which is responsible for
|
||||
/// handling the authentication and authorization processes. It is used by
|
||||
/// this controller to issue authorization codes and access tokens as part of
|
||||
/// the OAuth 2.0 flow.
|
||||
///
|
||||
/// The [AuthServer] instance should be properly configured and initialized
|
||||
/// before being assigned to this property.
|
||||
late final AuthServer authServer;
|
||||
|
||||
/// Determines whether the controller allows the OAuth 2.0 Implicit Grant Flow.
|
||||
///
|
||||
/// When set to true, the controller will process requests for access tokens
|
||||
/// directly (response_type=token). When false, such requests will be rejected.
|
||||
///
|
||||
/// This property is typically set in the constructor and should not be
|
||||
/// modified after initialization.
|
||||
/// When true, the controller allows for the Implicit Grant Flow
|
||||
final bool allowsImplicit;
|
||||
|
||||
/// A randomly generated value the client can use to verify the origin of the redirect.
|
||||
///
|
||||
/// This property is bound to the 'state' query parameter of the incoming request.
|
||||
/// It serves as a security measure to prevent cross-site request forgery (CSRF) attacks.
|
||||
///
|
||||
/// Clients must include this query parameter when initiating an authorization request.
|
||||
/// Upon receiving a redirect from this server, clients should verify that the 'state'
|
||||
/// value in the redirect matches the one they initially sent. This ensures that the
|
||||
/// response is for the request they initiated and not for a malicious request.
|
||||
///
|
||||
/// The value of 'state' is typically a randomly generated string or session identifier.
|
||||
/// It should be unique for each authorization request to maintain security.
|
||||
///
|
||||
/// Example usage:
|
||||
/// ```
|
||||
/// GET /authorize?response_type=code&client_id=CLIENT_ID&state=RANDOM_STATE
|
||||
/// ```
|
||||
/// Clients must include this query parameter and verify that any redirects from this
|
||||
/// server have the same value for 'state' as passed in. This value is usually a randomly generated
|
||||
/// session identifier.
|
||||
@Bind.query("state")
|
||||
String? state;
|
||||
|
||||
/// The type of response requested from the authorization endpoint.
|
||||
///
|
||||
/// This property is bound to the 'response_type' query parameter of the incoming request.
|
||||
/// It must be either 'code' or 'token':
|
||||
/// - 'code': Indicates that the client is initiating the authorization code flow.
|
||||
/// - 'token': Indicates that the client is initiating the implicit flow.
|
||||
///
|
||||
/// The value of this property determines the type of credential (authorization code or access token)
|
||||
/// that will be issued upon successful authentication.
|
||||
///
|
||||
/// Note: The availability of the 'token' response type depends on the [allowsImplicit] setting
|
||||
/// of the controller.
|
||||
/// Must be 'code' or 'token'.
|
||||
@Bind.query("response_type")
|
||||
String? responseType;
|
||||
|
||||
/// The client ID of the authenticating client.
|
||||
///
|
||||
/// This property is bound to the 'client_id' query parameter of the incoming request.
|
||||
/// It represents the unique identifier of the client application requesting authorization.
|
||||
///
|
||||
/// The client ID must be registered and valid according to the [authServer].
|
||||
/// It is used to identify the client during the authorization process and to ensure
|
||||
/// that only authorized clients can request access tokens or authorization codes.
|
||||
///
|
||||
/// This field is nullable, but typically required for most OAuth 2.0 flows.
|
||||
/// If not provided in the request, it may lead to authorization failures.
|
||||
///
|
||||
/// Example usage in a request URL:
|
||||
/// ```
|
||||
/// GET /authorize?client_id=my_client_id&...
|
||||
/// ```
|
||||
/// This must be a valid client ID according to [authServer].\
|
||||
@Bind.query("client_id")
|
||||
String? clientID;
|
||||
|
||||
/// Delegate responsible for rendering the HTML login form.
|
||||
///
|
||||
/// If provided, this delegate will be used to generate a custom login page
|
||||
/// when [getAuthorizationPage] is called. The delegate's [render] method
|
||||
/// is responsible for creating the HTML content of the login form.
|
||||
///
|
||||
/// When this property is null, the controller will not serve a login page
|
||||
/// and will respond with a 405 Method Not Allowed status for GET requests.
|
||||
///
|
||||
/// This delegate allows for customization of the login experience while
|
||||
/// maintaining the required OAuth 2.0 authorization flow.
|
||||
/// Renders an HTML login form.
|
||||
final AuthRedirectControllerDelegate? delegate;
|
||||
|
||||
/// Returns an HTML login form for OAuth 2.0 authorization.
|
||||
/// Returns an HTML login form.
|
||||
///
|
||||
/// A client that wishes to authenticate with this server should direct the user
|
||||
/// to this page. The user will enter their username and password that is sent as a POST
|
||||
|
|
@ -242,10 +129,9 @@ class AuthRedirectController extends ResourceController {
|
|||
|
||||
/// Creates a one-time use authorization code or an access token.
|
||||
///
|
||||
/// This method handles the OAuth 2.0 authorization process, responding with a redirect
|
||||
/// that contains either an authorization code ('code') or an access token ('token')
|
||||
/// along with the passed in 'state'. If the request fails, the redirect URL will
|
||||
/// contain an 'error' instead of the authorization code or access token.
|
||||
/// This method will respond with a redirect that either contains an authorization code ('code')
|
||||
/// or an access token ('token') along with the passed in 'state'. If this request fails,
|
||||
/// the redirect URL will contain an 'error' instead of the authorization code or access token.
|
||||
///
|
||||
/// This method is typically invoked by the login form returned from the GET to this controller.
|
||||
@Operation.post()
|
||||
|
|
@ -343,19 +229,6 @@ class AuthRedirectController extends ResourceController {
|
|||
}
|
||||
}
|
||||
|
||||
/// Customizes the API documentation for the request body of this controller's operations.
|
||||
///
|
||||
/// This method overrides the default implementation to add specific details to the
|
||||
/// POST operation's request body schema:
|
||||
/// - Sets the format of the 'password' field to "password".
|
||||
/// - Marks 'client_id', 'state', 'response_type', 'username', and 'password' as required fields.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - context: The API documentation context.
|
||||
/// - operation: The operation being documented.
|
||||
///
|
||||
/// Returns:
|
||||
/// The modified [APIRequestBody] object, or null if no modifications were made.
|
||||
@override
|
||||
APIRequestBody? documentOperationRequestBody(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -376,20 +249,6 @@ class AuthRedirectController extends ResourceController {
|
|||
return body;
|
||||
}
|
||||
|
||||
/// Customizes the API documentation for the operation parameters of this controller.
|
||||
///
|
||||
/// This method overrides the default implementation to mark all parameters
|
||||
/// as required, except for the 'scope' parameter. It does this by:
|
||||
/// 1. Calling the superclass method to get the initial list of parameters.
|
||||
/// 2. Iterating through all parameters except 'scope'.
|
||||
/// 3. Setting the 'isRequired' property of each parameter to true.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - context: The API documentation context.
|
||||
/// - operation: The operation being documented.
|
||||
///
|
||||
/// Returns:
|
||||
/// A list of [APIParameter] objects with updated 'isRequired' properties.
|
||||
@override
|
||||
List<APIParameter> documentOperationParameters(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -402,29 +261,6 @@ class AuthRedirectController extends ResourceController {
|
|||
return params;
|
||||
}
|
||||
|
||||
/// Generates API documentation for the responses of this controller's operations.
|
||||
///
|
||||
/// This method overrides the default implementation to provide custom documentation
|
||||
/// for the GET and POST operations of the AuthRedirectController.
|
||||
///
|
||||
/// For GET requests:
|
||||
/// - Documents a 200 response that serves a login form in HTML format.
|
||||
///
|
||||
/// For POST requests:
|
||||
/// - Documents a 302 (Moved Temporarily) response for successful authorizations,
|
||||
/// explaining the structure of the redirect URI for both 'code' and 'token' response types.
|
||||
/// - Documents a 400 (Bad Request) response for cases where the client ID is invalid
|
||||
/// and the redirect URI cannot be verified.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - context: The API documentation context.
|
||||
/// - operation: The operation being documented.
|
||||
///
|
||||
/// Returns:
|
||||
/// A Map of status codes to APIResponse objects describing the possible responses.
|
||||
///
|
||||
/// Throws:
|
||||
/// StateError if documentation fails (i.e., for unexpected HTTP methods).
|
||||
@override
|
||||
Map<String, APIResponse> documentOperationResponses(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -462,24 +298,6 @@ class AuthRedirectController extends ResourceController {
|
|||
throw StateError("AuthRedirectController documentation failed.");
|
||||
}
|
||||
|
||||
/// Customizes the API documentation for the operations of this controller.
|
||||
///
|
||||
/// This method overrides the default implementation to update the authorization URLs
|
||||
/// for both the Authorization Code Flow and Implicit Flow in the API documentation.
|
||||
///
|
||||
/// It performs the following steps:
|
||||
/// 1. Calls the superclass method to get the initial operations documentation.
|
||||
/// 2. Constructs a URI from the given route.
|
||||
/// 3. Sets this URI as the authorization URL for both the Authorization Code Flow
|
||||
/// and the Implicit Flow in the auth server's documentation.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - context: The API documentation context.
|
||||
/// - route: The route string for this controller.
|
||||
/// - path: The APIPath object representing this controller's path.
|
||||
///
|
||||
/// Returns:
|
||||
/// A Map of operation IDs to APIOperation objects describing the operations of this controller.
|
||||
@override
|
||||
Map<String, APIOperation> documentOperations(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -493,27 +311,6 @@ class AuthRedirectController extends ResourceController {
|
|||
return ops;
|
||||
}
|
||||
|
||||
/// Generates a redirect response for OAuth 2.0 authorization flow.
|
||||
///
|
||||
/// This method constructs a redirect URI based on the given parameters and the type of response
|
||||
/// (code or token) requested. It handles both successful authorizations and error cases.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [inputUri]: The base URI to redirect to. If null, falls back to the client's registered redirect URI.
|
||||
/// - [clientStateOrNull]: The state parameter provided by the client for CSRF protection.
|
||||
/// - [code]: The authorization code (for code flow).
|
||||
/// - [token]: The access token (for token/implicit flow).
|
||||
/// - [error]: Any error that occurred during the authorization process.
|
||||
///
|
||||
/// Returns:
|
||||
/// - A [Response] object with a 302 status code and appropriate headers for redirection.
|
||||
/// - If the redirect URI is invalid or cannot be constructed, returns a 400 Bad Request response.
|
||||
///
|
||||
/// The method constructs the redirect URI as follows:
|
||||
/// - For 'code' response type: Adds code, state, and error (if any) as query parameters.
|
||||
/// - For 'token' response type: Adds token details, state, and error (if any) as URI fragment.
|
||||
///
|
||||
/// The response includes headers to prevent caching of the redirect.
|
||||
Response _redirectResponse(
|
||||
String? inputUri,
|
||||
String? clientStateOrNull, {
|
||||
|
|
|
|||
|
|
@ -1,23 +1,5 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:convert';
|
||||
|
||||
/// An abstract class for parsing authorization headers.
|
||||
///
|
||||
/// This class defines a common interface for parsing different types of
|
||||
/// authorization headers. Implementations of this class should provide
|
||||
/// specific parsing logic for different authorization schemes (e.g., Bearer, Basic).
|
||||
///
|
||||
/// The type parameter [T] represents the return type of the [parse] method,
|
||||
/// allowing for flexibility in the parsed result (e.g., String for Bearer tokens,
|
||||
/// custom credential objects for other schemes).
|
||||
abstract class AuthorizationParser<T> {
|
||||
const AuthorizationParser();
|
||||
|
||||
|
|
@ -25,24 +7,11 @@ abstract class AuthorizationParser<T> {
|
|||
}
|
||||
|
||||
/// Parses a Bearer token from an Authorization header.
|
||||
///
|
||||
/// This class extends [AuthorizationParser] and specializes in parsing Bearer tokens
|
||||
/// from Authorization headers. It implements the [parse] method to extract the token
|
||||
/// from a given header string.
|
||||
///
|
||||
/// Usage:
|
||||
/// ```dart
|
||||
/// final parser = AuthorizationBearerParser();
|
||||
/// final token = parser.parse("Bearer myToken123");
|
||||
/// print(token); // Outputs: myToken123
|
||||
/// ```
|
||||
///
|
||||
/// If the header is invalid or missing, it throws an [AuthorizationParserException]
|
||||
/// with an appropriate [AuthorizationParserExceptionReason].
|
||||
class AuthorizationBearerParser extends AuthorizationParser<String?> {
|
||||
const AuthorizationBearerParser();
|
||||
|
||||
/// Parses a Bearer token from an Authorization header.
|
||||
/// Parses a Bearer token from [authorizationHeader]. If the header is malformed or doesn't exist,
|
||||
/// throws an [AuthorizationParserException]. Otherwise, returns the [String] representation of the bearer token.
|
||||
///
|
||||
/// For example, if the input to this method is "Bearer token" it would return 'token'.
|
||||
///
|
||||
|
|
@ -68,26 +37,6 @@ class AuthorizationBearerParser extends AuthorizationParser<String?> {
|
|||
|
||||
/// A structure to hold Basic authorization credentials.
|
||||
///
|
||||
/// This class represents the credentials used in Basic HTTP Authentication.
|
||||
/// It contains two properties: [username] and [password].
|
||||
///
|
||||
/// The [username] and [password] are marked as `late final`, indicating that
|
||||
/// they must be initialized before use, but can only be set once.
|
||||
///
|
||||
/// This class is typically used in conjunction with [AuthorizationBasicParser]
|
||||
/// to parse and store credentials from a Basic Authorization header.
|
||||
///
|
||||
/// The [toString] method is overridden to provide a string representation
|
||||
/// of the credentials in the format "username:password".
|
||||
///
|
||||
/// Example usage:
|
||||
/// ```dart
|
||||
/// final credentials = AuthBasicCredentials()
|
||||
/// ..username = 'john_doe'
|
||||
/// ..password = 'secret123';
|
||||
/// print(credentials); // Outputs: john_doe:secret123
|
||||
/// ```
|
||||
///
|
||||
/// See [AuthorizationBasicParser] for getting instances of this type.
|
||||
class AuthBasicCredentials {
|
||||
/// The username of a Basic Authorization header.
|
||||
|
|
@ -101,38 +50,14 @@ class AuthBasicCredentials {
|
|||
}
|
||||
|
||||
/// Parses a Basic Authorization header.
|
||||
///
|
||||
/// This class extends [AuthorizationParser] and specializes in parsing Basic Authentication
|
||||
/// credentials from Authorization headers. It implements the [parse] method to extract
|
||||
/// the username and password from a given header string.
|
||||
///
|
||||
/// The parser expects the header to be in the format "Basic <base64-encoded-credentials>",
|
||||
/// where the credentials are a string of "username:password" encoded in Base64.
|
||||
///
|
||||
/// Usage:
|
||||
/// ```dart
|
||||
/// final parser = AuthorizationBasicParser();
|
||||
/// final credentials = parser.parse("Basic dXNlcm5hbWU6cGFzc3dvcmQ=");
|
||||
/// print(credentials.username); // Outputs: username
|
||||
/// print(credentials.password); // Outputs: password
|
||||
/// ```
|
||||
///
|
||||
/// If the header is invalid, missing, or cannot be properly decoded, it throws an
|
||||
/// [AuthorizationParserException] with an appropriate [AuthorizationParserExceptionReason].
|
||||
class AuthorizationBasicParser
|
||||
extends AuthorizationParser<AuthBasicCredentials> {
|
||||
/// Creates a constant instance of [AuthorizationBasicParser].
|
||||
///
|
||||
/// This constructor allows for the creation of immutable instances of the parser,
|
||||
/// which can be safely shared and reused across multiple parts of an application.
|
||||
///
|
||||
/// Example usage:
|
||||
/// ```dart
|
||||
/// final parser = const AuthorizationBasicParser();
|
||||
/// ```
|
||||
const AuthorizationBasicParser();
|
||||
|
||||
/// Parses a Basic Authorization header and returns [AuthBasicCredentials].
|
||||
/// Returns a [AuthBasicCredentials] containing the username and password
|
||||
/// base64 encoded in [authorizationHeader]. For example, if the input to this method
|
||||
/// was 'Basic base64String' it would decode the base64String
|
||||
/// and return the username and password by splitting that decoded string around the character ':'.
|
||||
///
|
||||
/// If [authorizationHeader] is malformed or null, throws an [AuthorizationParserException].
|
||||
@override
|
||||
|
|
@ -175,49 +100,10 @@ class AuthorizationBasicParser
|
|||
}
|
||||
}
|
||||
|
||||
/// Enumerates the possible reasons for authorization parsing failures.
|
||||
///
|
||||
/// This enum is used in conjunction with [AuthorizationParserException] to
|
||||
/// provide more specific information about why the parsing of an authorization
|
||||
/// header failed.
|
||||
///
|
||||
/// The enum contains two values:
|
||||
/// - [missing]: Indicates that the required authorization header was not present.
|
||||
/// - [malformed]: Indicates that the authorization header was present but its
|
||||
/// format was incorrect or could not be properly parsed.
|
||||
///
|
||||
/// This enum is typically used by [AuthorizationBearerParser] and
|
||||
/// [AuthorizationBasicParser] to specify the nature of parsing failures.
|
||||
/// The reason either [AuthorizationBearerParser] or [AuthorizationBasicParser] failed.
|
||||
enum AuthorizationParserExceptionReason { missing, malformed }
|
||||
|
||||
/// An exception class for errors encountered during authorization parsing.
|
||||
///
|
||||
/// This exception is thrown when there's an issue parsing an authorization header.
|
||||
/// It contains a [reason] field of type [AuthorizationParserExceptionReason]
|
||||
/// which provides more specific information about why the parsing failed.
|
||||
///
|
||||
/// The [reason] can be either [AuthorizationParserExceptionReason.missing]
|
||||
/// (indicating the absence of a required authorization header) or
|
||||
/// [AuthorizationParserExceptionReason.malformed] (indicating an incorrectly
|
||||
/// formatted authorization header).
|
||||
///
|
||||
/// This exception is typically thrown by implementations of [AuthorizationParser],
|
||||
/// such as [AuthorizationBearerParser] and [AuthorizationBasicParser].
|
||||
///
|
||||
/// Example usage:
|
||||
/// ```dart
|
||||
/// try {
|
||||
/// parser.parse(header);
|
||||
/// } catch (e) {
|
||||
/// if (e is AuthorizationParserException) {
|
||||
/// if (e.reason == AuthorizationParserExceptionReason.missing) {
|
||||
/// print('Authorization header is missing');
|
||||
/// } else if (e.reason == AuthorizationParserExceptionReason.malformed) {
|
||||
/// print('Authorization header is malformed');
|
||||
/// }
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
/// An exception indicating why Authorization parsing failed.
|
||||
class AuthorizationParserException implements Exception {
|
||||
AuthorizationParserException(this.reason);
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:math';
|
||||
|
||||
|
|
@ -17,10 +8,9 @@ import 'package:crypto/crypto.dart';
|
|||
|
||||
/// A OAuth 2.0 authorization server.
|
||||
///
|
||||
/// This class implements the core functionality of an OAuth 2.0 authorization server,
|
||||
/// including client management, token issuance, token refresh, and token verification.
|
||||
/// It supports various OAuth 2.0 flows such as password, client credentials, authorization code,
|
||||
/// and refresh token.
|
||||
/// An [AuthServer] is an implementation of an OAuth 2.0 authorization server. An authorization server
|
||||
/// issues, refreshes and revokes access tokens. It also verifies previously issued tokens, as
|
||||
/// well as client and resource owner credentials.
|
||||
///
|
||||
/// [AuthServer]s are typically used in conjunction with [AuthController] and [AuthRedirectController].
|
||||
/// These controllers provide HTTP interfaces to the [AuthServer] for issuing and refreshing tokens.
|
||||
|
|
@ -67,29 +57,9 @@ import 'package:crypto/crypto.dart';
|
|||
/// }
|
||||
///
|
||||
class AuthServer implements AuthValidator, APIComponentDocumenter {
|
||||
/// This constructor initializes an [AuthServer] with the provided [delegate],
|
||||
/// which is responsible for managing authentication-related data storage and retrieval.
|
||||
/// Creates a new instance of an [AuthServer] with a [delegate].
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [delegate]: An instance of [AuthServerDelegate] that handles data persistence.
|
||||
/// - [hashRounds]: The number of iterations for password hashing. Defaults to 1000.
|
||||
/// - [hashLength]: The length of the generated hash in bytes. Defaults to 32.
|
||||
/// - [hashFunction]: The hash function to use. Defaults to [sha256].
|
||||
///
|
||||
/// The [hashRounds], [hashLength], and [hashFunction] parameters configure the
|
||||
/// password hashing mechanism used by this [AuthServer] instance. These values
|
||||
/// affect the security and performance of password hashing operations.
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// final delegate = MyAuthServerDelegate();
|
||||
/// final authServer = AuthServer(
|
||||
/// delegate,
|
||||
/// hashRounds: 1000,
|
||||
/// hashLength: 32,
|
||||
/// hashFunction: sha256,
|
||||
/// );
|
||||
/// ```
|
||||
/// [hashFunction] defaults to [sha256].
|
||||
AuthServer(
|
||||
this.delegate, {
|
||||
this.hashRounds = 1000,
|
||||
|
|
@ -104,117 +74,32 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
///
|
||||
/// It is preferable to use the implementation of [AuthServerDelegate] from 'package:conduit_core/managed_auth.dart'. See
|
||||
/// [AuthServer] for more details.
|
||||
///
|
||||
/// This delegate plays a crucial role in the OAuth 2.0 flow by managing the persistence
|
||||
/// of authentication-related objects. It abstracts away the storage implementation,
|
||||
/// allowing for flexibility in how these objects are stored (e.g., in-memory, database).
|
||||
///
|
||||
/// The delegate is responsible for the following main tasks:
|
||||
/// 1. Storing and retrieving AuthClient information
|
||||
/// 2. Managing AuthToken lifecycle (creation, retrieval, and revocation)
|
||||
/// 3. Handling AuthCode operations for the authorization code flow
|
||||
/// 4. Fetching ResourceOwner information for authentication purposes
|
||||
///
|
||||
/// Implementations of this delegate should ensure thread-safety and efficient
|
||||
/// data access to maintain the performance and security of the authentication server.
|
||||
final AuthServerDelegate delegate;
|
||||
|
||||
/// The number of hashing rounds performed by this instance when validating a password.
|
||||
///
|
||||
/// This value determines the number of iterations the password hashing algorithm
|
||||
/// will perform. A higher number of rounds increases the computational cost and
|
||||
/// time required to hash a password, making it more resistant to brute-force attacks.
|
||||
/// However, it also increases the time needed for legitimate password verification.
|
||||
///
|
||||
/// The optimal value balances security and performance based on the specific
|
||||
/// requirements of the application. Common values range from 1000 to 50000,
|
||||
/// but may need adjustment based on hardware capabilities and security needs.
|
||||
final int hashRounds;
|
||||
|
||||
/// The resulting key length of a password hash when generated by this instance.
|
||||
///
|
||||
/// This value determines the length (in bytes) of the generated password hash.
|
||||
/// A longer hash length generally provides more security against certain types of attacks,
|
||||
/// but also requires more storage space. Common values range from 16 to 64 bytes.
|
||||
///
|
||||
/// This parameter is used in conjunction with [hashRounds] and [hashFunction]
|
||||
/// to configure the password hashing algorithm (typically PBKDF2).
|
||||
final int hashLength;
|
||||
|
||||
/// The [Hash] function used by the PBKDF2 algorithm to generate password hashes by this instance.
|
||||
///
|
||||
/// This function is used in the password hashing process to create secure, one-way
|
||||
/// hashes of passwords. The PBKDF2 (Password-Based Key Derivation Function 2)
|
||||
/// algorithm uses this hash function repeatedly to increase the computational cost
|
||||
/// of cracking the resulting hash.
|
||||
///
|
||||
/// By default, this is set to [sha256], but it can be customized to use other
|
||||
/// cryptographic hash functions if needed. The choice of hash function affects
|
||||
/// the security and performance characteristics of the password hashing process.
|
||||
///
|
||||
/// This property works in conjunction with [hashRounds] and [hashLength] to
|
||||
/// configure the overall password hashing strategy of the AuthServer.
|
||||
final Hash hashFunction;
|
||||
|
||||
/// Represents the OAuth 2.0 Authorization Code flow for OpenAPI documentation purposes.
|
||||
///
|
||||
/// This property is used to document the Authorization Code flow in the OpenAPI
|
||||
/// specification generated for this AuthServer. It is initialized as an empty
|
||||
/// OAuth2 flow with an empty scopes map, which can be populated later with
|
||||
/// the specific scopes supported by the server.
|
||||
///
|
||||
/// The Authorization Code flow is a secure way of obtaining access tokens
|
||||
/// that involves a client application directing the resource owner to an
|
||||
/// authorization server to grant permission, then using the resulting
|
||||
/// authorization code to obtain an access token.
|
||||
///
|
||||
/// This property is typically used in conjunction with the `documentComponents`
|
||||
/// method to properly document the OAuth2 security scheme in the API specification.
|
||||
/// Used during OpenAPI documentation.
|
||||
final APISecuritySchemeOAuth2Flow documentedAuthorizationCodeFlow =
|
||||
APISecuritySchemeOAuth2Flow.empty()..scopes = {};
|
||||
|
||||
/// Represents the OAuth 2.0 Password flow for OpenAPI documentation purposes.
|
||||
///
|
||||
/// This property is used to document the Password flow in the OpenAPI
|
||||
/// specification generated for this AuthServer. It is initialized as an empty
|
||||
/// OAuth2 flow with an empty scopes map, which can be populated later with
|
||||
/// the specific scopes supported by the server for the Password flow.
|
||||
///
|
||||
/// The Password flow allows users to exchange their username and password
|
||||
/// directly for an access token. This flow should only be used by trusted
|
||||
/// applications due to its sensitivity in handling user credentials.
|
||||
///
|
||||
/// This property is typically used in conjunction with the `documentComponents`
|
||||
/// method to properly document the OAuth2 security scheme in the API specification.
|
||||
/// Used during OpenAPI documentation.
|
||||
final APISecuritySchemeOAuth2Flow documentedPasswordFlow =
|
||||
APISecuritySchemeOAuth2Flow.empty()..scopes = {};
|
||||
|
||||
/// Represents the OAuth 2.0 Implicit flow for OpenAPI documentation purposes.
|
||||
///
|
||||
/// This property is used to document the Implicit flow in the OpenAPI
|
||||
/// specification generated for this AuthServer. It is initialized as an empty
|
||||
/// OAuth2 flow with an empty scopes map, which can be populated later with
|
||||
/// the specific scopes supported by the server for the Implicit flow.
|
||||
///
|
||||
/// The Implicit flow is designed for client-side applications (e.g., single-page web apps)
|
||||
/// where the access token is returned immediately without an extra authorization code
|
||||
/// exchange step. This flow has some security trade-offs and is generally not recommended
|
||||
/// for new implementations.
|
||||
///
|
||||
/// This property is typically used in conjunction with the `documentComponents`
|
||||
/// method to properly document the OAuth2 security scheme in the API specification.
|
||||
/// Used during OpenAPI documentation.
|
||||
final APISecuritySchemeOAuth2Flow documentedImplicitFlow =
|
||||
APISecuritySchemeOAuth2Flow.empty()..scopes = {};
|
||||
|
||||
/// Constant representing the token type "bearer" for OAuth 2.0 access tokens.
|
||||
///
|
||||
/// This value is used to specify the type of token issued by the authorization server.
|
||||
/// The "bearer" token type is defined in RFC 6750 and is the most common type used in OAuth 2.0.
|
||||
/// Bearer tokens can be used by any party in possession of the token to access protected resources
|
||||
/// without demonstrating possession of a cryptographic key.
|
||||
static const String tokenTypeBearer = "bearer";
|
||||
|
||||
/// Hashes a password using the PBKDF2 algorithm.
|
||||
/// Hashes a [password] with [salt] using PBKDF2 algorithm.
|
||||
///
|
||||
/// See [hashRounds], [hashLength] and [hashFunction] for more details. This method
|
||||
/// invoke [auth.generatePasswordHash] with the above inputs.
|
||||
|
|
@ -228,7 +113,7 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
);
|
||||
}
|
||||
|
||||
/// Adds a new OAuth2 client to the authentication server.
|
||||
/// Adds an OAuth2 client.
|
||||
///
|
||||
/// [delegate] will store this client for future use.
|
||||
Future addClient(AuthClient client) async {
|
||||
|
|
@ -247,14 +132,14 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
return delegate.addClient(this, client);
|
||||
}
|
||||
|
||||
/// Retrieves an [AuthClient] record based on the provided [clientID].
|
||||
/// Returns a [AuthClient] record for its [clientID].
|
||||
///
|
||||
/// Returns null if none exists.
|
||||
Future<AuthClient?> getClient(String clientID) async {
|
||||
return delegate.getClient(this, clientID);
|
||||
}
|
||||
|
||||
/// Revokes and removes an [AuthClient] record associated with the given [clientID].
|
||||
/// Revokes a [AuthClient] record.
|
||||
///
|
||||
/// Removes cached occurrences of [AuthClient] for [clientID].
|
||||
/// Asks [delegate] to remove an [AuthClient] by its ID via [AuthServerDelegate.removeClient].
|
||||
|
|
@ -266,7 +151,7 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
return delegate.removeClient(this, clientID);
|
||||
}
|
||||
|
||||
/// Revokes all access grants for a specific resource owner.
|
||||
/// Revokes access for an [ResourceOwner].
|
||||
///
|
||||
/// All authorization codes and tokens for the [ResourceOwner] identified by [identifier]
|
||||
/// will be revoked.
|
||||
|
|
@ -278,7 +163,7 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
await delegate.removeTokens(this, identifier);
|
||||
}
|
||||
|
||||
/// Authenticates a username and password of a [ResourceOwner] and returns an [AuthToken] upon success.
|
||||
/// Authenticates a username and password of an [ResourceOwner] and returns an [AuthToken] upon success.
|
||||
///
|
||||
/// This method works with this instance's [delegate] to generate and store a new token if all credentials are correct.
|
||||
/// If credentials are not correct, it will throw the appropriate [AuthRequestError].
|
||||
|
|
@ -345,7 +230,7 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
return token;
|
||||
}
|
||||
|
||||
/// Verifies the validity of an access token and returns an [Authorization] object.
|
||||
/// Returns a [Authorization] for [accessToken].
|
||||
///
|
||||
/// This method obtains an [AuthToken] for [accessToken] from [delegate] and then verifies that the token is valid.
|
||||
/// If the token is valid, an [Authorization] object is returned. Otherwise, an [AuthServerException] is thrown.
|
||||
|
|
@ -384,34 +269,9 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
|
||||
/// Refreshes a valid [AuthToken] instance.
|
||||
///
|
||||
/// This method refreshes an existing [AuthToken] using its [refreshToken] for a given client ID.
|
||||
/// It coordinates with the instance's [delegate] to update the old token with a new access token
|
||||
/// and issue/expiration dates if successful. If unsuccessful, it throws an [AuthRequestError].
|
||||
///
|
||||
/// The method performs several validation steps:
|
||||
/// 1. Verifies the client ID and retrieves the corresponding [AuthClient].
|
||||
/// 2. Checks for the presence of a refresh token.
|
||||
/// 3. Retrieves the existing token using the refresh token.
|
||||
/// 4. Validates the client secret.
|
||||
/// 5. Handles scope validation and updates:
|
||||
/// - If new scopes are requested, it ensures they are subsets of existing scopes and allowed by the client.
|
||||
/// - If no new scopes are requested, it verifies that existing scopes are still valid for the client.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [refreshToken]: The refresh token of the [AuthToken] to be refreshed.
|
||||
/// - [clientID]: The ID of the client requesting the token refresh.
|
||||
/// - [clientSecret]: The secret of the client requesting the token refresh.
|
||||
/// - [requestedScopes]: Optional list of scopes to be applied to the refreshed token.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [Future] that resolves to a new [AuthToken] with updated access token, issue date, and expiration date.
|
||||
///
|
||||
/// Throws:
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidClient] if the client ID is invalid or empty.
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidRequest] if the refresh token is missing.
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidGrant] if the token is not found or doesn't match the client ID.
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidClient] if the client secret is invalid.
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidScope] if the requested scopes are invalid or not allowed.
|
||||
/// This method will refresh a [AuthToken] given the [AuthToken]'s [refreshToken] for a given client ID.
|
||||
/// This method coordinates with this instance's [delegate] to update the old token with a new access token and issue/expiration dates if successful.
|
||||
/// If not successful, it will throw an [AuthRequestError].
|
||||
Future<AuthToken> refresh(
|
||||
String? refreshToken,
|
||||
String clientID,
|
||||
|
|
@ -496,34 +356,9 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
|
||||
/// Creates a one-time use authorization code for a given client ID and user credentials.
|
||||
///
|
||||
/// This method is part of the OAuth 2.0 Authorization Code flow. It authenticates a user
|
||||
/// with their username and password for a specific client, and if successful, generates
|
||||
/// a short-lived authorization code.
|
||||
///
|
||||
/// The method performs several steps:
|
||||
/// 1. Validates the client ID and retrieves the client information.
|
||||
/// 2. Authenticates the user with the provided username and password.
|
||||
/// 3. Validates the requested scopes against the client's allowed scopes and the user's permissions.
|
||||
/// 4. Generates a new authorization code.
|
||||
/// 5. Stores the authorization code using the delegate.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [username]: The username of the resource owner (user).
|
||||
/// - [password]: The password of the resource owner.
|
||||
/// - [clientID]: The ID of the client requesting the authorization code.
|
||||
/// - [expirationInSeconds]: The lifetime of the authorization code in seconds (default is 600 seconds or 10 minutes).
|
||||
/// - [requestedScopes]: Optional list of scopes the client is requesting access to.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [Future] that resolves to an [AuthCode] object representing the generated authorization code.
|
||||
///
|
||||
/// Throws:
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidClient] if the client ID is invalid or empty.
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidRequest] if the username or password is missing.
|
||||
/// - [AuthServerException] with [AuthRequestError.unauthorizedClient] if the client doesn't have a redirect URI.
|
||||
/// - [AuthServerException] with [AuthRequestError.accessDenied] if the user credentials are invalid.
|
||||
///
|
||||
/// The generated authorization code can later be exchanged for an access token using the `exchange` method.
|
||||
/// This methods works with this instance's [delegate] to generate and store the authorization code
|
||||
/// if the credentials are correct. If they are not correct, it will throw the
|
||||
/// appropriate [AuthRequestError].
|
||||
Future<AuthCode> authenticateForCode(
|
||||
String? username,
|
||||
String? password,
|
||||
|
|
@ -573,35 +408,9 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
|
||||
/// Exchanges a valid authorization code for an [AuthToken].
|
||||
///
|
||||
/// This method is part of the OAuth 2.0 Authorization Code flow. It allows a client
|
||||
/// to exchange a previously obtained authorization code for an access token.
|
||||
///
|
||||
/// The method performs several validation steps:
|
||||
/// 1. Verifies the client ID and retrieves the corresponding [AuthClient].
|
||||
/// 2. Checks for the presence of the authorization code.
|
||||
/// 3. Validates the client secret.
|
||||
/// 4. Retrieves and validates the stored authorization code.
|
||||
/// 5. Checks if the authorization code is still valid and hasn't been used.
|
||||
/// 6. Ensures the client ID matches the one associated with the authorization code.
|
||||
///
|
||||
/// If all validations pass, it generates a new access token and stores it using the delegate.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [authCodeString]: The authorization code to be exchanged.
|
||||
/// - [clientID]: The ID of the client requesting the token exchange.
|
||||
/// - [clientSecret]: The secret of the client requesting the token exchange.
|
||||
/// - [expirationInSeconds]: The lifetime of the generated access token in seconds (default is 3600 seconds or 1 hour).
|
||||
///
|
||||
/// Returns:
|
||||
/// A [Future] that resolves to an [AuthToken] representing the newly created access token.
|
||||
///
|
||||
/// Throws:
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidClient] if the client ID is invalid or empty, or if the client secret is incorrect.
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidRequest] if the authorization code is missing.
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidGrant] if the authorization code is invalid, expired, or has been used before.
|
||||
///
|
||||
/// This method is crucial for completing the Authorization Code flow, allowing clients
|
||||
/// to securely obtain access tokens after receiving user authorization.
|
||||
/// If the authorization code has not expired, has not been used, matches the client ID,
|
||||
/// and the client secret is correct, it will return a valid [AuthToken]. Otherwise,
|
||||
/// it will throw an appropriate [AuthRequestError].
|
||||
Future<AuthToken> exchange(
|
||||
String? authCodeString,
|
||||
String clientID,
|
||||
|
|
@ -665,22 +474,6 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
//////
|
||||
// APIDocumentable overrides
|
||||
//////
|
||||
|
||||
/// Generates and registers security schemes for API documentation.
|
||||
///
|
||||
/// This method is responsible for documenting the security components of the API,
|
||||
/// specifically the OAuth2 client authentication and standard OAuth2 flows.
|
||||
///
|
||||
/// It performs the following tasks:
|
||||
/// 1. Registers a basic HTTP authentication scheme for OAuth2 client authentication.
|
||||
/// 2. Creates and registers an OAuth2 security scheme with authorization code and password flows.
|
||||
/// 3. Defers cleanup of unused flows based on the presence of required URLs.
|
||||
///
|
||||
/// The method uses the [APIDocumentContext] to register these security schemes,
|
||||
/// making them available for use in the API documentation.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [context]: The [APIDocumentContext] used to register security schemes and defer cleanup operations.
|
||||
@override
|
||||
void documentComponents(APIDocumentContext context) {
|
||||
final basic = APISecurityScheme.http("basic")
|
||||
|
|
@ -715,27 +508,6 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
/////
|
||||
// AuthValidator overrides
|
||||
/////
|
||||
|
||||
/// Documents the security requirements for an [Authorizer] in the API specification.
|
||||
///
|
||||
/// This method generates the appropriate [APISecurityRequirement] objects
|
||||
/// based on the type of authorization parser used by the [Authorizer].
|
||||
///
|
||||
/// For basic authentication (AuthorizationBasicParser), it specifies the
|
||||
/// requirement for OAuth2 client authentication.
|
||||
///
|
||||
/// For bearer token authentication (AuthorizationBearerParser), it specifies
|
||||
/// the requirement for OAuth2 with optional scopes.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [context]: The API documentation context.
|
||||
/// - [authorizer]: The Authorizer instance for which to generate requirements.
|
||||
/// - [scopes]: Optional list of scopes to be included in the OAuth2 requirement.
|
||||
///
|
||||
/// Returns:
|
||||
/// A list of [APISecurityRequirement] objects representing the security
|
||||
/// requirements for the given authorizer. Returns an empty list if the
|
||||
/// parser type is not recognized.
|
||||
@override
|
||||
List<APISecurityRequirement> documentRequirementsForAuthorizer(
|
||||
APIDocumentContext context,
|
||||
|
|
@ -757,25 +529,6 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
return [];
|
||||
}
|
||||
|
||||
/// Validates an authorization request using the specified parser and authorization data.
|
||||
///
|
||||
/// This method is responsible for validating different types of authorization,
|
||||
/// including client credentials (Basic) and bearer tokens.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [parser]: An instance of [AuthorizationParser] used to parse the authorization data.
|
||||
/// - [authorizationData]: The authorization data to be validated, type depends on the parser.
|
||||
/// - [requiredScope]: Optional list of [AuthScope]s required for the authorization.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [FutureOr<Authorization>] representing the validated authorization.
|
||||
///
|
||||
/// Throws:
|
||||
/// - [ArgumentError] if an invalid parser is provided.
|
||||
///
|
||||
/// The method behaves differently based on the type of parser:
|
||||
/// - For [AuthorizationBasicParser], it validates client credentials.
|
||||
/// - For [AuthorizationBearerParser], it verifies the bearer token.
|
||||
@override
|
||||
FutureOr<Authorization> validate<T>(
|
||||
AuthorizationParser<T> parser,
|
||||
|
|
@ -794,31 +547,6 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
);
|
||||
}
|
||||
|
||||
/// Validates client credentials for OAuth 2.0 client authentication.
|
||||
///
|
||||
/// This method is used to authenticate a client using its client ID and secret
|
||||
/// as part of the OAuth 2.0 client authentication process.
|
||||
///
|
||||
/// The method performs the following steps:
|
||||
/// 1. Retrieves the client using the provided client ID (username).
|
||||
/// 2. Validates the client's existence and secret.
|
||||
/// 3. For public clients (no secret), it allows authentication with an empty password.
|
||||
/// 4. For confidential clients, it verifies the provided password against the stored hashed secret.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [credentials]: An [AuthBasicCredentials] object containing the client ID (username) and secret (password).
|
||||
///
|
||||
/// Returns:
|
||||
/// A [Future<Authorization>] representing the authenticated client.
|
||||
///
|
||||
/// Throws:
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidClient] if:
|
||||
/// - The client is not found.
|
||||
/// - A public client provides a non-empty password.
|
||||
/// - A confidential client provides an incorrect secret.
|
||||
///
|
||||
/// This method is typically used in the context of the client credentials grant type
|
||||
/// or when a client needs to authenticate itself for other OAuth 2.0 flows.
|
||||
Future<Authorization> _validateClientCredentials(
|
||||
AuthBasicCredentials credentials,
|
||||
) async {
|
||||
|
|
@ -846,29 +574,6 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
return Authorization(client.id, null, this, credentials: credentials);
|
||||
}
|
||||
|
||||
/// Validates and filters the requested scopes for a client and resource owner.
|
||||
///
|
||||
/// This method checks the requested scopes against the client's allowed scopes
|
||||
/// and the resource owner's permitted scopes. It ensures that only valid and
|
||||
/// authorized scopes are granted.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [client]: The [AuthClient] requesting the scopes.
|
||||
/// - [authenticatable]: The [ResourceOwner] being authenticated.
|
||||
/// - [requestedScopes]: The list of [AuthScope]s requested by the client.
|
||||
///
|
||||
/// Returns:
|
||||
/// A list of validated [AuthScope]s that are allowed for both the client and
|
||||
/// the resource owner. Returns null if the client doesn't support scopes.
|
||||
///
|
||||
/// Throws:
|
||||
/// - [AuthServerException] with [AuthRequestError.invalidScope] if:
|
||||
/// - The client supports scopes but no scopes are requested.
|
||||
/// - None of the requested scopes are allowed for the client.
|
||||
/// - The filtered scopes are not allowed for the resource owner.
|
||||
///
|
||||
/// This method is crucial for maintaining the principle of least privilege
|
||||
/// in OAuth 2.0 flows by ensuring that tokens are issued with appropriate scopes.
|
||||
List<AuthScope>? _validatedScopes(
|
||||
AuthClient client,
|
||||
ResourceOwner authenticatable,
|
||||
|
|
@ -906,24 +611,6 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
return validScopes;
|
||||
}
|
||||
|
||||
/// Generates a new [AuthToken] with the specified parameters.
|
||||
///
|
||||
/// This method creates and initializes a new [AuthToken] object with the given
|
||||
/// owner ID, client ID, and expiration time. It also sets other properties such
|
||||
/// as the access token, issue date, token type, and optional refresh token.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [ownerID]: The identifier of the resource owner (user).
|
||||
/// - [clientID]: The identifier of the client application.
|
||||
/// - [expirationInSeconds]: The number of seconds until the token expires.
|
||||
/// - [allowRefresh]: Whether to generate a refresh token (default is true).
|
||||
/// - [scopes]: Optional list of scopes associated with the token.
|
||||
///
|
||||
/// Returns:
|
||||
/// A new [AuthToken] instance with all properties set according to the input parameters.
|
||||
///
|
||||
/// The access token and refresh token (if allowed) are generated as random strings.
|
||||
/// The token type is set to "bearer" as defined by [tokenTypeBearer].
|
||||
AuthToken _generateToken(
|
||||
int? ownerID,
|
||||
String clientID,
|
||||
|
|
@ -948,24 +635,6 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
return token;
|
||||
}
|
||||
|
||||
/// Generates a new [AuthCode] with the specified parameters.
|
||||
///
|
||||
/// This method creates and initializes a new [AuthCode] object with the given
|
||||
/// owner ID, client, and expiration time. It also sets other properties such
|
||||
/// as the authorization code, issue date, and optional scopes.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [ownerID]: The identifier of the resource owner (user).
|
||||
/// - [client]: The [AuthClient] for which the auth code is being generated.
|
||||
/// - [expirationInSeconds]: The number of seconds until the auth code expires.
|
||||
/// - [scopes]: Optional list of scopes associated with the auth code.
|
||||
///
|
||||
/// Returns:
|
||||
/// A new [AuthCode] instance with all properties set according to the input parameters.
|
||||
///
|
||||
/// The authorization code is generated as a random string of 32 characters.
|
||||
/// The issue date is set to the current UTC time, and the expiration date is
|
||||
/// calculated based on the [expirationInSeconds] parameter.
|
||||
AuthCode _generateAuthCode(
|
||||
int? ownerID,
|
||||
AuthClient client,
|
||||
|
|
@ -983,19 +652,6 @@ class AuthServer implements AuthValidator, APIComponentDocumenter {
|
|||
}
|
||||
}
|
||||
|
||||
/// Generates a random string of specified length.
|
||||
///
|
||||
/// This function creates a random string using a combination of uppercase letters,
|
||||
/// lowercase letters, and digits. It uses a cryptographically secure random number
|
||||
/// generator to ensure unpredictability.
|
||||
///
|
||||
/// The function works by repeatedly selecting random characters from a predefined
|
||||
/// set of possible characters and appending them to a string buffer. The selection
|
||||
/// process uses the modulo operation to ensure an even distribution across the
|
||||
/// character set.
|
||||
///
|
||||
/// Returns:
|
||||
/// A string of the specified [length] containing random characters.
|
||||
String randomStringOfLength(int length) {
|
||||
const possibleCharacters =
|
||||
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
|
||||
|
|
|
|||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'dart:io';
|
||||
|
||||
|
|
@ -17,9 +8,8 @@ import 'package:protevus_openapi/v3.dart';
|
|||
|
||||
/// A [Controller] that validates the Authorization header of a request.
|
||||
///
|
||||
/// This class, Authorizer, is responsible for authenticating and authorizing incoming HTTP requests.
|
||||
/// It validates the Authorization header, processes it according to the specified parser (e.g., Bearer or Basic),
|
||||
/// and then uses the provided validator to check the credentials.
|
||||
/// An instance of this type will validate that the authorization information in an Authorization header is sufficient to access
|
||||
/// the next controller in the channel.
|
||||
///
|
||||
/// For each request, this controller parses the authorization header, validates it with an [AuthValidator] and then create an [Authorization] object
|
||||
/// if successful. The [Request] keeps a reference to this [Authorization] and is then sent to the next controller in the channel.
|
||||
|
|
@ -38,7 +28,7 @@ import 'package:protevus_openapi/v3.dart';
|
|||
class Authorizer extends Controller {
|
||||
/// Creates an instance of [Authorizer].
|
||||
///
|
||||
/// This constructor allows for creating an [Authorizer] with custom configurations.
|
||||
/// Use this constructor to provide custom [AuthorizationParser]s.
|
||||
///
|
||||
/// By default, this instance will parse bearer tokens from the authorization header, e.g.:
|
||||
///
|
||||
|
|
@ -53,11 +43,7 @@ class Authorizer extends Controller {
|
|||
|
||||
/// Creates an instance of [Authorizer] with Basic Authentication parsing.
|
||||
///
|
||||
/// This constructor initializes an [Authorizer] that uses Basic Authentication.
|
||||
/// It sets up the [Authorizer] to parse the Authorization header of incoming requests
|
||||
/// using the [AuthorizationBasicParser].
|
||||
///
|
||||
/// The Authorization header for Basic Authentication should be in the format:
|
||||
/// Parses a username and password from the request's Basic Authentication data in the Authorization header, e.g.:
|
||||
///
|
||||
/// Authorization: Basic base64(username:password)
|
||||
Authorizer.basic(AuthValidator? validator)
|
||||
|
|
@ -65,9 +51,7 @@ class Authorizer extends Controller {
|
|||
|
||||
/// Creates an instance of [Authorizer] with Bearer token parsing.
|
||||
///
|
||||
/// This constructor initializes an [Authorizer] that uses Bearer token authentication.
|
||||
/// It sets up the [Authorizer] to parse the Authorization header of incoming requests
|
||||
/// using the [AuthorizationBearerParser].
|
||||
/// Parses a bearer token from the request's Authorization header, e.g.
|
||||
///
|
||||
/// Authorization: Bearer ap9ijlarlkz8jIOa9laweo
|
||||
///
|
||||
|
|
@ -81,19 +65,12 @@ class Authorizer extends Controller {
|
|||
|
||||
/// The validating authorization object.
|
||||
///
|
||||
/// This property holds an instance of [AuthValidator] responsible for validating
|
||||
/// the credentials parsed from the Authorization header. It processes these
|
||||
/// credentials and produces an [Authorization] object that represents the
|
||||
/// authorization level of the provided credentials.
|
||||
///
|
||||
/// The validator can also reject a request if the credentials are invalid or
|
||||
/// insufficient. This property is typically set to an instance of [AuthServer].
|
||||
///
|
||||
/// The validator is crucial for determining whether a request should be allowed
|
||||
/// to proceed based on the provided authorization information.
|
||||
/// This object will check credentials parsed from the Authorization header and produce an
|
||||
/// [Authorization] object representing the authorization the credentials have. It may also
|
||||
/// reject a request. This is typically an instance of [AuthServer].
|
||||
final AuthValidator? validator;
|
||||
|
||||
/// The list of required scopes for authorization.
|
||||
/// The list of required scopes.
|
||||
///
|
||||
/// If [validator] grants scope-limited authorizations (e.g., OAuth2 bearer tokens), the authorization
|
||||
/// provided by the request's header must have access to all [scopes] in order to move on to the next controller.
|
||||
|
|
@ -102,7 +79,7 @@ class Authorizer extends Controller {
|
|||
/// an [AuthScope] and added to this list.
|
||||
final List<AuthScope>? scopes;
|
||||
|
||||
/// Parses the Authorization header of incoming requests.
|
||||
/// Parses the Authorization header.
|
||||
///
|
||||
/// The parser determines how to interpret the data in the Authorization header. Concrete subclasses
|
||||
/// are [AuthorizationBasicParser] and [AuthorizationBearerParser].
|
||||
|
|
@ -110,20 +87,6 @@ class Authorizer extends Controller {
|
|||
/// Once parsed, the parsed value is validated by [validator].
|
||||
final AuthorizationParser parser;
|
||||
|
||||
/// Handles the incoming request by validating its authorization.
|
||||
///
|
||||
/// This method performs the following steps:
|
||||
/// 1. Extracts the Authorization header from the request.
|
||||
/// 2. If the header is missing, returns an unauthorized response.
|
||||
/// 3. Attempts to parse the authorization data using the configured parser.
|
||||
/// 4. Validates the parsed data using the configured validator.
|
||||
/// 5. If validation succeeds, adds the authorization to the request and proceeds.
|
||||
/// 6. If validation fails due to insufficient scope, returns a forbidden response.
|
||||
/// 7. For other validation failures, returns an unauthorized response.
|
||||
/// 8. Handles parsing exceptions by returning appropriate error responses.
|
||||
///
|
||||
/// @param request The incoming HTTP request to be authorized.
|
||||
/// @return A [Future] that resolves to either the authorized [Request] or an error [Response].
|
||||
@override
|
||||
FutureOr<RequestOrResponse> handle(Request request) async {
|
||||
final authData = request.raw.headers.value(HttpHeaders.authorizationHeader);
|
||||
|
|
@ -158,19 +121,6 @@ class Authorizer extends Controller {
|
|||
return request;
|
||||
}
|
||||
|
||||
/// Generates an appropriate HTTP response based on the type of AuthorizationParserException.
|
||||
///
|
||||
/// This method takes an [AuthorizationParserException] as input and returns
|
||||
/// a [Response] object based on the exception's reason:
|
||||
///
|
||||
/// - For [AuthorizationParserExceptionReason.malformed], it returns a 400 Bad Request
|
||||
/// response with a body indicating an invalid authorization header.
|
||||
/// - For [AuthorizationParserExceptionReason.missing], it returns a 401 Unauthorized
|
||||
/// response.
|
||||
/// - For any other reason, it returns a 500 Server Error response.
|
||||
///
|
||||
/// @param e The AuthorizationParserException that occurred during parsing.
|
||||
/// @return A Response object appropriate to the exception reason.
|
||||
Response _responseFromParseException(AuthorizationParserException e) {
|
||||
switch (e.reason) {
|
||||
case AuthorizationParserExceptionReason.malformed:
|
||||
|
|
@ -184,21 +134,6 @@ class Authorizer extends Controller {
|
|||
}
|
||||
}
|
||||
|
||||
/// Adds a response modifier to the request to handle scope requirements.
|
||||
///
|
||||
/// This method is called after successful authorization and adds a response
|
||||
/// modifier to the request. The modifier's purpose is to enhance 403 (Forbidden)
|
||||
/// responses that are due to insufficient scope.
|
||||
///
|
||||
/// If this [Authorizer] has required scopes and the response is a 403 with a body
|
||||
/// containing a "scope" key, this modifier will add any of this [Authorizer]'s
|
||||
/// required scopes that aren't already present in the response body's scope list.
|
||||
///
|
||||
/// This ensures that if a downstream controller returns a 403 due to insufficient
|
||||
/// scope, the response includes all the scopes required by both this [Authorizer]
|
||||
/// and the downstream controller.
|
||||
///
|
||||
/// @param request The [Request] object to which the modifier will be added.
|
||||
void _addScopeRequirementModifier(Request request) {
|
||||
// If a controller returns a 403 because of invalid scope,
|
||||
// this Authorizer adds its required scope as well.
|
||||
|
|
@ -219,49 +154,10 @@ class Authorizer extends Controller {
|
|||
}
|
||||
}
|
||||
|
||||
/// Documents the components for the API documentation.
|
||||
///
|
||||
/// This method is responsible for registering custom API responses that are specific
|
||||
/// to authorization-related errors. It adds three responses to the API documentation:
|
||||
///
|
||||
/// 1. "InsufficientScope": Used when the provided credentials or bearer token have
|
||||
/// insufficient permissions to access a route.
|
||||
///
|
||||
/// 2. "InsufficientAccess": Used when the provided credentials or bearer token are
|
||||
/// not authorized for a specific request.
|
||||
///
|
||||
/// 3. "MalformedAuthorizationHeader": Used when the provided Authorization header
|
||||
/// is malformed.
|
||||
///
|
||||
/// Each response is registered with a description and a schema defining the
|
||||
/// structure of the JSON response body.
|
||||
///
|
||||
/// @param context The APIDocumentContext used to register the responses.
|
||||
@override
|
||||
void documentComponents(APIDocumentContext context) {
|
||||
/// Calls the superclass's documentComponents method.
|
||||
///
|
||||
/// This method invokes the documentComponents method of the superclass,
|
||||
/// ensuring that any component documentation defined in the parent class
|
||||
/// is properly registered in the API documentation context.
|
||||
///
|
||||
/// @param context The APIDocumentContext used for registering API components.
|
||||
super.documentComponents(context);
|
||||
|
||||
/// Registers an "InsufficientScope" response in the API documentation.
|
||||
///
|
||||
/// This response is used when the provided credentials or bearer token
|
||||
/// have insufficient permissions to access a specific route. It includes
|
||||
/// details about the error and the required scope for the operation.
|
||||
///
|
||||
/// The response has the following structure:
|
||||
/// - A description explaining the insufficient scope error.
|
||||
/// - Content of type "application/json" with a schema containing:
|
||||
/// - An "error" field of type string.
|
||||
/// - A "scope" field of type string, describing the required scope.
|
||||
///
|
||||
/// This response can be referenced in API operations to standardize
|
||||
/// the documentation of insufficient scope errors.
|
||||
context.responses.register(
|
||||
"InsufficientScope",
|
||||
APIResponse(
|
||||
|
|
@ -278,19 +174,6 @@ class Authorizer extends Controller {
|
|||
),
|
||||
);
|
||||
|
||||
/// Registers an "InsufficientAccess" response in the API documentation.
|
||||
///
|
||||
/// This response is used when the provided credentials or bearer token
|
||||
/// are not authorized for a specific request. It includes details about
|
||||
/// the error in a JSON format.
|
||||
///
|
||||
/// The response has the following structure:
|
||||
/// - A description explaining the insufficient access error.
|
||||
/// - Content of type "application/json" with a schema containing:
|
||||
/// - An "error" field of type string.
|
||||
///
|
||||
/// This response can be referenced in API operations to standardize
|
||||
/// the documentation of insufficient access errors.
|
||||
context.responses.register(
|
||||
"InsufficientAccess",
|
||||
APIResponse(
|
||||
|
|
@ -305,18 +188,6 @@ class Authorizer extends Controller {
|
|||
),
|
||||
);
|
||||
|
||||
/// Registers a "MalformedAuthorizationHeader" response in the API documentation.
|
||||
///
|
||||
/// This response is used when the provided Authorization header is malformed.
|
||||
/// It includes details about the error in a JSON format.
|
||||
///
|
||||
/// The response has the following structure:
|
||||
/// - A description explaining the malformed authorization header error.
|
||||
/// - Content of type "application/json" with a schema containing:
|
||||
/// - An "error" field of type string.
|
||||
///
|
||||
/// This response can be referenced in API operations to standardize
|
||||
/// the documentation of malformed authorization header errors.
|
||||
context.responses.register(
|
||||
"MalformedAuthorizationHeader",
|
||||
APIResponse(
|
||||
|
|
@ -332,23 +203,6 @@ class Authorizer extends Controller {
|
|||
);
|
||||
}
|
||||
|
||||
/// Documents the operations for the API documentation.
|
||||
///
|
||||
/// This method is responsible for adding security-related responses and requirements
|
||||
/// to each operation in the API documentation. It performs the following tasks:
|
||||
///
|
||||
/// 1. Calls the superclass's documentOperations method to get the base operations.
|
||||
/// 2. For each operation:
|
||||
/// - Adds a 400 response for malformed authorization headers.
|
||||
/// - Adds a 401 response for insufficient access.
|
||||
/// - Adds a 403 response for insufficient scope.
|
||||
/// - Retrieves security requirements from the validator.
|
||||
/// - Adds these security requirements to the operation.
|
||||
///
|
||||
/// @param context The APIDocumentContext used for documenting the API.
|
||||
/// @param route The route string for which operations are being documented.
|
||||
/// @param path The APIPath object representing the path of the operations.
|
||||
/// @return A map of operation names to APIOperation objects with added security documentation.
|
||||
@override
|
||||
Map<String, APIOperation> documentOperations(
|
||||
APIDocumentContext context,
|
||||
|
|
|
|||
|
|
@ -1,58 +1,11 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'package:protevus_auth/auth.dart';
|
||||
|
||||
/// An exception class for handling authentication server errors.
|
||||
///
|
||||
/// This class implements the [Exception] interface and is used to represent
|
||||
/// various errors that can occur during the authentication process.
|
||||
///
|
||||
/// The [AuthServerException] contains:
|
||||
/// - [reason]: An [AuthRequestError] enum value representing the specific error.
|
||||
/// - [client]: An optional [AuthClient] associated with the error.
|
||||
///
|
||||
/// It also provides utility methods:
|
||||
/// - [errorString]: A static method that converts [AuthRequestError] enum values to standardized error strings.
|
||||
/// - [reasonString]: A getter that returns the error string for the current [reason].
|
||||
///
|
||||
/// The [toString] method is overridden to provide a custom string representation of the exception.
|
||||
/// An exception thrown by [AuthServer].
|
||||
class AuthServerException implements Exception {
|
||||
/// Creates an [AuthServerException] with the specified [reason] and optional [client].
|
||||
///
|
||||
/// The [reason] parameter is an [AuthRequestError] enum value representing the specific error.
|
||||
/// The [client] parameter is an optional [AuthClient] associated with the error.
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// var exception = AuthServerException(AuthRequestError.invalidRequest, null);
|
||||
/// ```
|
||||
AuthServerException(this.reason, this.client);
|
||||
|
||||
/// Converts an [AuthRequestError] enum value to its corresponding string representation.
|
||||
///
|
||||
/// This static method takes an [AuthRequestError] as input and returns a standardized
|
||||
/// string that represents the error. These strings are suitable for inclusion in
|
||||
/// query strings or JSON response bodies when indicating errors during the processing
|
||||
/// of OAuth 2.0 requests.
|
||||
///
|
||||
/// The returned strings conform to the error codes defined in the OAuth 2.0 specification,
|
||||
/// with the exception of 'invalid_token', which is a custom addition.
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// var errorString = AuthServerException.errorString(AuthRequestError.invalidRequest);
|
||||
/// print(errorString); // Outputs: "invalid_request"
|
||||
/// ```
|
||||
///
|
||||
/// @param error The [AuthRequestError] enum value to convert.
|
||||
/// @return A string representation of the error.
|
||||
/// Returns a string suitable to be included in a query string or JSON response body
|
||||
/// to indicate the error during processing an OAuth 2.0 request.
|
||||
static String errorString(AuthRequestError error) {
|
||||
switch (error) {
|
||||
case AuthRequestError.invalidRequest:
|
||||
|
|
@ -83,54 +36,25 @@ class AuthServerException implements Exception {
|
|||
}
|
||||
}
|
||||
|
||||
/// The specific reason for the authentication error.
|
||||
///
|
||||
/// This property holds an [AuthRequestError] enum value that represents
|
||||
/// the specific error that occurred during the authentication process.
|
||||
/// It provides detailed information about why the authentication request failed.
|
||||
AuthRequestError reason;
|
||||
|
||||
/// The optional [AuthClient] associated with this exception.
|
||||
///
|
||||
/// This property may contain an [AuthClient] instance that is related to the
|
||||
/// authentication error. It can be null if no specific client is associated
|
||||
/// with the error or if the error occurred before client authentication.
|
||||
///
|
||||
/// This information can be useful for debugging or logging purposes, providing
|
||||
/// context about which client encountered the authentication error.
|
||||
AuthClient? client;
|
||||
|
||||
/// Returns a string representation of the [reason] for this exception.
|
||||
///
|
||||
/// This getter utilizes the static [errorString] method to convert the
|
||||
/// [AuthRequestError] enum value stored in [reason] to its corresponding
|
||||
/// string representation.
|
||||
///
|
||||
/// @return A standardized string representation of the error reason.
|
||||
String get reasonString {
|
||||
return errorString(reason);
|
||||
}
|
||||
|
||||
/// Returns a string representation of the [AuthServerException].
|
||||
///
|
||||
/// This method overrides the default [Object.toString] method to provide
|
||||
/// a custom string representation of the exception. The returned string
|
||||
/// includes the exception class name, the [reason] for the exception,
|
||||
/// and the associated [client] (if any).
|
||||
///
|
||||
/// @return A string in the format "AuthServerException: [reason] [client]".
|
||||
@override
|
||||
String toString() {
|
||||
return "AuthServerException: $reason $client";
|
||||
}
|
||||
}
|
||||
|
||||
/// Enum representing possible errors as defined by the OAuth 2.0 specification.
|
||||
/// The possible errors as defined by the OAuth 2.0 specification.
|
||||
///
|
||||
/// Auth endpoints will use this list of values to determine the response sent back
|
||||
/// to a client upon a failed request.
|
||||
enum AuthRequestError {
|
||||
/// Represents an invalid request error.
|
||||
/// The request was invalid...
|
||||
///
|
||||
/// The request is missing a required parameter, includes an
|
||||
/// unsupported parameter value (other than grant type),
|
||||
|
|
@ -139,7 +63,7 @@ enum AuthRequestError {
|
|||
/// client, or is otherwise malformed.
|
||||
invalidRequest,
|
||||
|
||||
/// Represents an invalid client error.
|
||||
/// The client was invalid...
|
||||
///
|
||||
/// Client authentication failed (e.g., unknown client, no
|
||||
/// client authentication included, or unsupported
|
||||
|
|
@ -153,7 +77,7 @@ enum AuthRequestError {
|
|||
/// matching the authentication scheme used by the client.
|
||||
invalidClient,
|
||||
|
||||
/// Represents an invalid grant error.
|
||||
/// The grant was invalid...
|
||||
///
|
||||
/// The provided authorization grant (e.g., authorization
|
||||
/// code, resource owner credentials) or refresh token is
|
||||
|
|
@ -162,81 +86,36 @@ enum AuthRequestError {
|
|||
/// another client.
|
||||
invalidGrant,
|
||||
|
||||
/// Represents an invalid scope error.
|
||||
/// The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
|
||||
///
|
||||
/// This error occurs when the requested scope is invalid, unknown, malformed,
|
||||
/// or exceeds the scope granted by the resource owner. It typically indicates
|
||||
/// that the client has requested access to resources or permissions that are
|
||||
/// either not recognized by the authorization server or not authorized for
|
||||
/// the particular client or user.
|
||||
///
|
||||
/// In the OAuth 2.0 flow, this error might be returned if a client requests
|
||||
/// access to a scope that doesn't exist or that the user hasn't granted
|
||||
/// permission for.
|
||||
invalidScope,
|
||||
|
||||
/// Represents an unsupported grant type error.
|
||||
/// The authorization grant type is not supported by the authorization server.
|
||||
///
|
||||
/// This error occurs when the authorization server does not support the
|
||||
/// grant type requested by the client. It typically indicates that the
|
||||
/// client has specified a grant type that is either not recognized or
|
||||
/// not implemented by the authorization server.
|
||||
///
|
||||
/// In the OAuth 2.0 flow, this error might be returned if, for example,
|
||||
/// a client requests a grant type like "password" when the server only
|
||||
/// supports "authorization_code" and "refresh_token" grant types.
|
||||
unsupportedGrantType,
|
||||
|
||||
/// Represents an unsupported response type error.
|
||||
/// The authorization server does not support obtaining an authorization code using this method.
|
||||
///
|
||||
/// This error occurs when the authorization server does not support obtaining
|
||||
/// an authorization code using the specified response type. It typically
|
||||
/// indicates that the client has requested a response type that is not
|
||||
/// recognized or not implemented by the authorization server.
|
||||
unsupportedResponseType,
|
||||
|
||||
/// Represents an unauthorized client error.
|
||||
/// The authenticated client is not authorized to use this authorization grant type.
|
||||
///
|
||||
/// This error occurs when the client is not authorized to request an
|
||||
/// authorization code using this method. It typically indicates that
|
||||
/// the client does not have the necessary permissions or credentials
|
||||
/// to perform the requested action, even though it may be properly
|
||||
/// authenticated.
|
||||
unauthorizedClient,
|
||||
|
||||
/// Represents an access denied error.
|
||||
/// The resource owner or authorization server denied the request.
|
||||
///
|
||||
/// This error occurs when the resource owner or authorization server denies the request.
|
||||
/// It is typically used when the authenticated user does not have sufficient permissions
|
||||
/// to perform the requested action, or when the user explicitly denies authorization
|
||||
/// during the OAuth flow.
|
||||
accessDenied,
|
||||
|
||||
/// Represents a server error.
|
||||
/// The server encountered an error during processing the request.
|
||||
///
|
||||
/// This error occurs when the authorization server encounters an unexpected
|
||||
/// condition that prevented it from fulfilling the request. This is typically
|
||||
/// used for internal server errors or other unexpected issues that prevent
|
||||
/// the server from properly processing the authentication request.
|
||||
serverError,
|
||||
|
||||
/// Represents a temporarily unavailable error.
|
||||
/// The server is temporarily unable to fulfill the request.
|
||||
///
|
||||
/// This error occurs when the authorization server is temporarily unable to handle
|
||||
/// the request due to a temporary overloading or maintenance of the server.
|
||||
/// The client may repeat the request at a later time. The server SHOULD include
|
||||
/// a Retry-After HTTP header field in the response indicating how long the client
|
||||
/// should wait before retrying the request.
|
||||
temporarilyUnavailable,
|
||||
|
||||
/// Represents an invalid token error.
|
||||
/// Indicates that the token is invalid.
|
||||
///
|
||||
/// This error occurs when the provided token is invalid, expired, or otherwise
|
||||
/// not acceptable for the requested operation. It is typically used when a client
|
||||
/// presents an access token that cannot be validated or is no longer valid.
|
||||
///
|
||||
/// Note: This particular error reason is not part of the standard OAuth 2.0
|
||||
/// specification. It is a custom addition to handle scenarios specific to
|
||||
/// token validation that are not covered by other standard error types.
|
||||
/// This particular error reason is not part of the OAuth 2.0 spec.
|
||||
invalidToken
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,32 +1,20 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'package:protevus_auth/auth.dart';
|
||||
import 'package:protevus_http/http.dart';
|
||||
|
||||
/// Represents an OAuth 2.0 client ID and secret pair.
|
||||
///
|
||||
/// This class encapsulates the information necessary for OAuth 2.0 client authentication.
|
||||
/// It can represent both public and confidential clients, with support for the authorization code grant flow.
|
||||
/// See the conduit/managed_auth library for a concrete implementation of this type.
|
||||
///
|
||||
/// Use the command line tool `conduit auth` to create instances of this type and store them to a database.
|
||||
class AuthClient {
|
||||
/// Creates an instance of [AuthClient].
|
||||
///
|
||||
/// This constructor creates an [AuthClient] with the given parameters.
|
||||
/// [id] must not be null. [hashedSecret] and [salt] must either both be null or both be valid values. If [hashedSecret] and [salt]
|
||||
/// are valid values, this client is a confidential client. Otherwise, the client is public. The terms 'confidential' and 'public'
|
||||
/// are described by the OAuth 2.0 specification.
|
||||
///
|
||||
/// If this client supports scopes, [allowedScopes] must contain a list of scopes that tokens may request when authorized
|
||||
/// by this client.
|
||||
///
|
||||
/// NOTE: [id] must not be null. [hashedSecret] and [salt] must either both be null or both be valid values. If [hashedSecret] and [salt]
|
||||
/// are valid values, this client is a confidential client. Otherwise, the client is public. The terms 'confidential' and 'public'
|
||||
/// are described by the OAuth 2.0 specification.
|
||||
AuthClient(
|
||||
String id,
|
||||
String? hashedSecret,
|
||||
|
|
@ -41,16 +29,6 @@ class AuthClient {
|
|||
);
|
||||
|
||||
/// Creates an instance of a public [AuthClient].
|
||||
///
|
||||
/// This constructor creates a public [AuthClient] with the given [id].
|
||||
/// Public clients do not have a client secret.
|
||||
///
|
||||
/// - [id]: The unique identifier for the client.
|
||||
/// - [allowedScopes]: Optional list of scopes that this client is allowed to request.
|
||||
/// - [redirectURI]: Optional URI to redirect to after authorization.
|
||||
///
|
||||
/// This is equivalent to calling [AuthClient.withRedirectURI] with null values for
|
||||
/// hashedSecret and salt.
|
||||
AuthClient.public(String id,
|
||||
{List<AuthScope>? allowedScopes, String? redirectURI})
|
||||
: this.withRedirectURI(
|
||||
|
|
@ -63,17 +41,7 @@ class AuthClient {
|
|||
|
||||
/// Creates an instance of [AuthClient] that uses the authorization code grant flow.
|
||||
///
|
||||
/// This constructor creates a confidential [AuthClient] with the given parameters.
|
||||
///
|
||||
/// - [id]: The unique identifier for the client.
|
||||
/// - [hashedSecret]: The hashed secret of the client.
|
||||
/// - [salt]: The salt used to hash the client secret.
|
||||
/// - [redirectURI]: The URI to redirect to after authorization.
|
||||
/// - [allowedScopes]: Optional list of scopes that this client is allowed to request.
|
||||
///
|
||||
/// This constructor is specifically for clients that use the authorization code grant flow,
|
||||
/// which requires a redirect URI. All parameters except [allowedScopes] must be non-null.
|
||||
/// The presence of [hashedSecret] and [salt] indicates that this is a confidential client.
|
||||
/// All values must be non-null. This is confidential client.
|
||||
AuthClient.withRedirectURI(
|
||||
this.id,
|
||||
this.hashedSecret,
|
||||
|
|
@ -84,57 +52,28 @@ class AuthClient {
|
|||
this.allowedScopes = allowedScopes;
|
||||
}
|
||||
|
||||
/// The list of allowed scopes for this client.
|
||||
///
|
||||
/// This private variable stores the allowed scopes for the AuthClient.
|
||||
/// It is used internally to manage and validate the scopes that this client
|
||||
/// is authorized to request during the authentication process.
|
||||
List<AuthScope>? _allowedScopes;
|
||||
|
||||
/// The unique identifier for this OAuth 2.0 client.
|
||||
///
|
||||
/// This is a required field for all OAuth 2.0 clients and is used to identify
|
||||
/// the client during the authentication and authorization process. It should
|
||||
/// be a string value that is unique among all clients registered with the
|
||||
/// authorization server.
|
||||
/// The ID of the client.
|
||||
final String id;
|
||||
|
||||
/// The hashed secret of the client.
|
||||
///
|
||||
/// This property stores the hashed version of the client's secret, which is used for authentication
|
||||
/// in confidential clients. The secret is hashed for security reasons, to avoid storing the raw secret.
|
||||
///
|
||||
/// This value may be null if the client is public. A null value indicates that this is a public client,
|
||||
/// which doesn't use a client secret for authentication. See [isPublic] for more information on
|
||||
/// determining if a client is public or confidential.
|
||||
///
|
||||
/// The hashed secret is typically used in conjunction with the [salt] property to verify
|
||||
/// the client's credentials during the authentication process.
|
||||
/// This value may be null if the client is public. See [isPublic].
|
||||
String? hashedSecret;
|
||||
|
||||
/// The salt used to hash the client secret.
|
||||
/// The salt [hashedSecret] was hashed with.
|
||||
///
|
||||
/// This value may be null if the client is public. See [isPublic].
|
||||
String? salt;
|
||||
|
||||
/// The redirection URI for authorization codes and/or tokens.
|
||||
///
|
||||
/// This property stores the URI where the authorization server should redirect
|
||||
/// the user after they grant or deny permission to the client. It is used in
|
||||
/// the authorization code grant flow of OAuth 2.0.
|
||||
///
|
||||
/// In the context of OAuth 2.0:
|
||||
/// - For authorization code grant, this URI is where the authorization code is sent.
|
||||
/// - For implicit grant, this URI is where the access token is sent.
|
||||
///
|
||||
/// This value may be null if the client doesn't support the authorization code flow.
|
||||
String? redirectURI;
|
||||
|
||||
/// The list of scopes available when authorizing with this client.
|
||||
///
|
||||
/// This getter returns the list of allowed scopes for the client. The setter
|
||||
/// filters the provided list to remove any redundant scopes.
|
||||
///
|
||||
/// Scoping is determined by this instance; i.e. the authorizing client determines which scopes a token
|
||||
/// has. This list contains all valid scopes for this client. If null, client does not support scopes
|
||||
/// and all access tokens have same authorization.
|
||||
|
|
@ -148,54 +87,32 @@ class AuthClient {
|
|||
}).toList();
|
||||
}
|
||||
|
||||
/// Determines if this instance supports authorization scopes.
|
||||
/// Whether or not this instance allows scoping or not.
|
||||
///
|
||||
/// In application's that do not use authorization scopes, this will return false.
|
||||
/// Otherwise, will return true.
|
||||
bool get supportsScopes => allowedScopes != null;
|
||||
|
||||
/// Determines if this client can issue tokens for the provided [scope].
|
||||
///
|
||||
/// This method checks if the given [scope] is allowed for this client by comparing it
|
||||
/// against the client's [allowedScopes]. It returns true if the provided [scope] is
|
||||
/// a subset of or equal to any of the scopes in [allowedScopes].
|
||||
///
|
||||
/// If [allowedScopes] is null or empty, this method returns false, indicating that
|
||||
/// no scopes are allowed for this client.
|
||||
///
|
||||
/// [scope]: The AuthScope to check against this client's allowed scopes.
|
||||
///
|
||||
/// Returns true if the scope is allowed, false otherwise.
|
||||
/// Whether or not this client can issue tokens for the provided [scope].
|
||||
bool allowsScope(AuthScope scope) {
|
||||
return allowedScopes
|
||||
?.any((clientScope) => scope.isSubsetOrEqualTo(clientScope)) ??
|
||||
false;
|
||||
}
|
||||
|
||||
/// Whether or not this is a public client.
|
||||
/// Whether or not this is a public or confidential client.
|
||||
///
|
||||
/// Public clients do not have a client secret and are used for clients that can't store
|
||||
/// their secret confidentially, i.e. JavaScript browser applications.
|
||||
bool get isPublic => hashedSecret == null;
|
||||
|
||||
/// Determines whether this client is confidential or public.
|
||||
/// Whether or not this is a public or confidential client.
|
||||
///
|
||||
/// Confidential clients have a client secret that must be used when authenticating with
|
||||
/// a client-authenticated request. Confidential clients are used when you can
|
||||
/// be sure that the client secret cannot be viewed by anyone outside of the developer.
|
||||
bool get isConfidential => hashedSecret != null;
|
||||
|
||||
/// Returns a string representation of the AuthClient instance.
|
||||
///
|
||||
/// This method provides a human-readable description of the AuthClient, including:
|
||||
/// - Whether the client is public or confidential
|
||||
/// - The client's ID
|
||||
/// - The client's redirect URI (if set)
|
||||
///
|
||||
/// The format of the returned string is:
|
||||
/// "AuthClient (public/confidential): [client_id] [redirect_uri]"
|
||||
///
|
||||
/// @return A string representation of the AuthClient.
|
||||
@override
|
||||
String toString() {
|
||||
return "AuthClient (${isPublic ? "public" : "confidental"}): $id $redirectURI";
|
||||
|
|
@ -204,67 +121,24 @@ class AuthClient {
|
|||
|
||||
/// Represents an OAuth 2.0 token.
|
||||
///
|
||||
/// This class encapsulates the properties and functionality of an OAuth 2.0 token,
|
||||
/// including access token, refresh token, expiration details, and associated scopes.
|
||||
/// It is used by [AuthServerDelegate] and [AuthServer] to exchange OAuth 2.0 tokens.
|
||||
/// [AuthServerDelegate] and [AuthServer] will exchange OAuth 2.0
|
||||
/// tokens through instances of this type.
|
||||
///
|
||||
/// See the `package:conduit_core/managed_auth` library for a concrete implementation of this type.
|
||||
class AuthToken {
|
||||
/// The access token string for OAuth 2.0 authentication.
|
||||
///
|
||||
/// This token is used in the Authorization header of HTTP requests to authenticate
|
||||
/// the client. It should be included in the header as "Bearer <accessToken>".
|
||||
///
|
||||
/// The access token is typically a short-lived credential that grants access to
|
||||
/// protected resources on behalf of the resource owner (user).
|
||||
///
|
||||
/// This value may be null if the token has not been issued or has been invalidated.
|
||||
/// The value to be passed as a Bearer Authorization header.
|
||||
String? accessToken;
|
||||
|
||||
/// The refresh token associated with this OAuth 2.0 token.
|
||||
///
|
||||
/// A refresh token is a credential that can be used to obtain a new access token
|
||||
/// when the current access token becomes invalid or expires. This allows the client
|
||||
/// to obtain continued access to protected resources without requiring the resource
|
||||
/// owner to re-authorize the application.
|
||||
///
|
||||
/// This value may be null if the authorization server does not issue refresh tokens
|
||||
/// or if the token has not been issued with a refresh token.
|
||||
/// The value to be passed for refreshing a token.
|
||||
String? refreshToken;
|
||||
|
||||
/// The time this token was issued on.
|
||||
///
|
||||
/// This property represents the date and time when the OAuth 2.0 token was originally issued.
|
||||
/// It can be used to calculate the age of the token or to implement token refresh policies.
|
||||
/// The value is stored as a [DateTime] object, which allows for easy manipulation and comparison.
|
||||
///
|
||||
/// This value may be null if the issue date is not tracked or has not been set.
|
||||
DateTime? issueDate;
|
||||
|
||||
/// The expiration date and time of this token.
|
||||
///
|
||||
/// This property represents the point in time when the OAuth 2.0 token will become invalid.
|
||||
/// After this date and time, the token should no longer be accepted for authentication.
|
||||
///
|
||||
/// The value is stored as a [DateTime] object, which allows for easy comparison with the current time
|
||||
/// to determine if the token has expired. This is typically used in conjunction with [issueDate]
|
||||
/// to calculate the token's lifespan and manage token refresh cycles.
|
||||
///
|
||||
/// This value may be null if the token does not have an expiration date or if it has not been set.
|
||||
/// The time when this token expires.
|
||||
DateTime? expirationDate;
|
||||
|
||||
/// The type of token used for authentication.
|
||||
///
|
||||
/// This property specifies the type of token being used. In the OAuth 2.0 framework,
|
||||
/// the most common token type is 'bearer'. The token type is typically used in the
|
||||
/// HTTP Authorization header to indicate how the access token should be used.
|
||||
///
|
||||
/// Currently, only 'bearer' is considered valid for this implementation.
|
||||
///
|
||||
/// Example usage in an HTTP header:
|
||||
/// Authorization: Bearer <access_token>
|
||||
///
|
||||
/// This value may be null if the token type has not been set or is unknown.
|
||||
/// The type of token, currently only 'bearer' is valid.
|
||||
String? type;
|
||||
|
||||
/// The identifier of the resource owner.
|
||||
|
|
@ -272,60 +146,15 @@ class AuthToken {
|
|||
/// Tokens are owned by a resource owner, typically a User, Profile or Account
|
||||
/// in an application. This value is the primary key or identifying value of those
|
||||
/// instances.
|
||||
///
|
||||
/// This property represents the unique identifier of the resource owner associated
|
||||
/// with the OAuth 2.0 token. It is typically used to link the token to a specific
|
||||
/// user or account in the system.
|
||||
///
|
||||
/// The value is stored as an integer, which could be:
|
||||
/// - A database primary key
|
||||
/// - A unique user ID
|
||||
/// - Any other numeric identifier that uniquely identifies the resource owner
|
||||
///
|
||||
/// This property may be null if the token is not associated with a specific
|
||||
/// resource owner or if the association has not been established.
|
||||
int? resourceOwnerIdentifier;
|
||||
|
||||
/// The client ID associated with this token.
|
||||
///
|
||||
/// This property represents the unique identifier of the OAuth 2.0 client
|
||||
/// that was used to obtain this token. It is used to link the token back
|
||||
/// to the client application that requested it.
|
||||
///
|
||||
/// The client ID is typically assigned by the authorization server when
|
||||
/// the client application is registered, and it's used to identify the
|
||||
/// client during the authentication and token issuance process.
|
||||
/// The client ID this token was issued from.
|
||||
late String clientID;
|
||||
|
||||
/// The list of authorization scopes associated with this token.
|
||||
///
|
||||
/// This property represents the set of permissions or access rights granted to this token.
|
||||
/// Each [AuthScope] in the list defines a specific area of access or functionality
|
||||
/// that the token holder is allowed to use.
|
||||
///
|
||||
/// The scopes determine what actions or resources the token can access within the system.
|
||||
/// If this list is null, it typically means the token has no specific scope restrictions
|
||||
/// and may have full access (depending on the system's implementation).
|
||||
///
|
||||
/// This property is crucial for implementing fine-grained access control in OAuth 2.0
|
||||
/// systems, allowing for precise definition of what each token is allowed to do.
|
||||
/// Scopes this token has access to.
|
||||
List<AuthScope>? scopes;
|
||||
|
||||
/// Determines whether this token has expired.
|
||||
///
|
||||
/// This getter compares the token's [expirationDate] with the current UTC time
|
||||
/// to determine if the token has expired. It returns true if the token has
|
||||
/// expired, and false if it is still valid.
|
||||
///
|
||||
/// The comparison is done by calculating the difference in seconds between
|
||||
/// the expiration date and the current time. If this difference is less than
|
||||
/// or equal to zero, the token is considered expired.
|
||||
///
|
||||
/// Returns:
|
||||
/// [bool]: true if the token has expired, false otherwise.
|
||||
///
|
||||
/// Note: This getter assumes that [expirationDate] is not null. If it is null,
|
||||
/// this will result in a null pointer exception.
|
||||
/// Whether or not this token is expired by evaluated [expirationDate].
|
||||
bool get isExpired {
|
||||
return expirationDate!.difference(DateTime.now().toUtc()).inSeconds <= 0;
|
||||
}
|
||||
|
|
@ -353,118 +182,37 @@ class AuthToken {
|
|||
|
||||
/// Represents an OAuth 2.0 authorization code.
|
||||
///
|
||||
/// This class encapsulates the properties and functionality of an OAuth 2.0 authorization code,
|
||||
/// which is used in the authorization code grant flow. It contains information such as the code itself,
|
||||
/// associated client and resource owner details, issue and expiration dates, and requested scopes.
|
||||
/// [AuthServerDelegate] and [AuthServer] will exchange OAuth 2.0
|
||||
/// authorization codes through instances of this type.
|
||||
///
|
||||
/// See the conduit/managed_auth library for a concrete implementation of this type.
|
||||
class AuthCode {
|
||||
/// The actual one-time code used to exchange for tokens.
|
||||
///
|
||||
/// This property represents the authorization code in the OAuth 2.0 authorization code flow.
|
||||
/// It is a short-lived, single-use code that is issued by the authorization server and can be
|
||||
/// exchanged for an access token and, optionally, a refresh token.
|
||||
///
|
||||
/// The code is typically valid for a short period (usually a few minutes) and can only be
|
||||
/// used once. After it has been exchanged for tokens, it becomes invalid.
|
||||
///
|
||||
/// This value may be null if the code has not been generated yet or has been invalidated.
|
||||
String? code;
|
||||
|
||||
/// The client ID associated with this authorization code.
|
||||
///
|
||||
/// This property represents the unique identifier of the OAuth 2.0 client
|
||||
/// that requested the authorization code. It is used to link the authorization
|
||||
/// code back to the client application that initiated the OAuth flow.
|
||||
///
|
||||
/// The client ID is typically assigned by the authorization server when
|
||||
/// the client application is registered, and it's used to identify the
|
||||
/// client during the authorization code exchange process.
|
||||
///
|
||||
/// This property is marked as 'late', indicating that it must be initialized
|
||||
/// before it's accessed, but not necessarily in the constructor.
|
||||
/// The client ID the authorization code was issued under.
|
||||
late String clientID;
|
||||
|
||||
/// The identifier of the resource owner associated with this authorization code.
|
||||
/// The identifier of the resource owner.
|
||||
///
|
||||
/// Authorization codes are owned by a resource owner, typically a User, Profile or Account
|
||||
/// in an application. This value is the primary key or identifying value of those
|
||||
/// instances.
|
||||
int? resourceOwnerIdentifier;
|
||||
|
||||
/// The timestamp when this authorization code was issued.
|
||||
///
|
||||
/// This property represents the date and time when the OAuth 2.0 authorization code
|
||||
/// was originally created and issued by the authorization server. It can be used to:
|
||||
/// - Calculate the age of the authorization code
|
||||
/// - Implement expiration policies
|
||||
/// - Audit the authorization process
|
||||
///
|
||||
/// The value is stored as a [DateTime] object, which allows for easy manipulation
|
||||
/// and comparison with other dates and times.
|
||||
///
|
||||
/// This value may be null if the issue date is not tracked or has not been set.
|
||||
/// The timestamp this authorization code was issued on.
|
||||
DateTime? issueDate;
|
||||
|
||||
/// The expiration date and time of this authorization code.
|
||||
///
|
||||
/// This property represents the point in time when the OAuth 2.0 authorization code
|
||||
/// will become invalid. After this date and time, the code should no longer be
|
||||
/// accepted for token exchange.
|
||||
///
|
||||
/// It is recommended to set this value to 10 minutes after the [issueDate] to
|
||||
/// limit the window of opportunity for potential attacks using intercepted
|
||||
/// authorization codes.
|
||||
///
|
||||
/// The value is stored as a [DateTime] object, which allows for easy comparison
|
||||
/// with the current time to determine if the code has expired. This is typically
|
||||
/// used in conjunction with [issueDate] to enforce the short-lived nature of
|
||||
/// authorization codes.
|
||||
///
|
||||
/// This value may be null if the authorization code does not have an expiration
|
||||
/// date or if it has not been set.
|
||||
/// When this authorization code expires, recommended for 10 minutes after issue date.
|
||||
DateTime? expirationDate;
|
||||
|
||||
/// Indicates whether this authorization code has already been exchanged for a token.
|
||||
///
|
||||
/// In the OAuth 2.0 authorization code flow, an authorization code should only be used once
|
||||
/// to obtain an access token. This property helps track whether the code has been exchanged.
|
||||
///
|
||||
/// - If `true`, the code has already been used to obtain a token and should not be accepted again.
|
||||
/// - If `false` or `null`, the code has not yet been exchanged and may still be valid for token issuance.
|
||||
///
|
||||
/// This property is crucial for preventing authorization code replay attacks, where an attacker
|
||||
/// might attempt to use a single authorization code multiple times.
|
||||
/// Whether or not this authorization code has already been exchanged for a token.
|
||||
bool? hasBeenExchanged;
|
||||
|
||||
/// The list of scopes requested for the token to be exchanged.
|
||||
///
|
||||
/// This property represents the set of permissions or access rights that are being
|
||||
/// requested for the OAuth 2.0 token during the authorization code exchange process.
|
||||
/// Each [AuthScope] in the list defines a specific area of access or functionality
|
||||
/// that the token is requesting to use.
|
||||
///
|
||||
/// If this list is null, it typically means no specific scopes are being requested,
|
||||
/// and the token may receive default scopes or full access (depending on the system's
|
||||
/// implementation and configuration).
|
||||
///
|
||||
/// The actual scopes granted to the token may be a subset of these requested scopes,
|
||||
/// based on the authorization server's policies and the resource owner's consent.
|
||||
/// Scopes the exchanged token will have.
|
||||
List<AuthScope>? requestedScopes;
|
||||
|
||||
/// Determines whether this authorization code has expired.
|
||||
///
|
||||
/// This getter compares the [expirationDate] of the authorization code with the current UTC time
|
||||
/// to determine if the code has expired. It returns true if the code has expired, and false if it is still valid.
|
||||
///
|
||||
/// The comparison is done by calculating the difference in seconds between the expiration date and the current time.
|
||||
/// If this difference is less than or equal to zero, the code is considered expired.
|
||||
///
|
||||
/// Returns:
|
||||
/// [bool]: true if the authorization code has expired, false otherwise.
|
||||
///
|
||||
/// Note: This getter assumes that [expirationDate] is not null. If it is null,
|
||||
/// this will result in a null pointer exception.
|
||||
/// Whether or not this code has expired yet, according to its [expirationDate].
|
||||
bool get isExpired {
|
||||
return expirationDate!.difference(DateTime.now().toUtc()).inSeconds <= 0;
|
||||
}
|
||||
|
|
@ -472,34 +220,12 @@ class AuthCode {
|
|||
|
||||
/// Authorization information for a [Request] after it has passed through an [Authorizer].
|
||||
///
|
||||
/// This class encapsulates various pieces of authorization information, including:
|
||||
/// - The client ID under which the permission was granted
|
||||
/// - The identifier for the resource owner (if applicable)
|
||||
/// - The [AuthValidator] that granted the permission
|
||||
/// - Basic authorization credentials (if provided)
|
||||
/// - A list of scopes that this authorization has access to
|
||||
///
|
||||
/// It also provides a method to check if the authorization has access to a specific scope.
|
||||
///
|
||||
/// This class is typically used in conjunction with [Authorizer] and [AuthValidator]
|
||||
/// to manage and verify authorization in a request-response cycle.
|
||||
/// After a request has passed through an [Authorizer], an instance of this type
|
||||
/// is created and attached to the request (see [Request.authorization]). Instances of this type contain the information
|
||||
/// that the [Authorizer] obtained from an [AuthValidator] (typically an [AuthServer])
|
||||
/// about the validity of the credentials in a request.
|
||||
class Authorization {
|
||||
/// Creates an instance of [Authorization].
|
||||
///
|
||||
/// This constructor initializes an [Authorization] object with the provided parameters:
|
||||
///
|
||||
/// - [clientID]: The client ID under which the permission was granted.
|
||||
/// - [ownerID]: The identifier for the owner of the resource, if provided. Can be null.
|
||||
/// - [validator]: The [AuthValidator] that granted this permission.
|
||||
/// - [credentials]: Optional. Basic authorization credentials, if provided.
|
||||
/// - [scopes]: Optional. The list of scopes this authorization has access to.
|
||||
///
|
||||
/// This class is typically used to represent the authorization information for a [Request]
|
||||
/// after it has passed through an [Authorizer].
|
||||
/// Creates an instance of a [Authorization].
|
||||
Authorization(
|
||||
this.clientID,
|
||||
this.ownerID,
|
||||
|
|
@ -508,71 +234,34 @@ class Authorization {
|
|||
this.scopes,
|
||||
});
|
||||
|
||||
/// The client ID associated with this authorization.
|
||||
///
|
||||
/// This property represents the unique identifier of the OAuth 2.0 client
|
||||
/// that was granted permission. It is used to link the authorization
|
||||
/// back to the specific client application that requested it.
|
||||
///
|
||||
/// The client ID is typically assigned by the authorization server when
|
||||
/// the client application is registered, and it's used to identify the
|
||||
/// client throughout the OAuth 2.0 flow.
|
||||
/// The client ID the permission was granted under.
|
||||
final String clientID;
|
||||
|
||||
/// The identifier for the owner of the resource, if provided.
|
||||
///
|
||||
/// This property represents the unique identifier of the resource owner associated
|
||||
/// with this authorization. In OAuth 2.0 terminology, the resource owner is typically
|
||||
/// the end-user who grants permission to an application to access their data.
|
||||
/// If this instance refers to the authorization of a resource owner, this value will
|
||||
/// be its identifying value. For example, in an application where a 'User' is stored in a database,
|
||||
/// this value would be the primary key of that user.
|
||||
///
|
||||
/// If this authorization does not refer to a specific resource owner, this value will be null.
|
||||
final int? ownerID;
|
||||
|
||||
/// The [AuthValidator] that granted this permission.
|
||||
///
|
||||
/// This property represents the [AuthValidator] instance that was responsible
|
||||
/// for validating and granting the authorization. It can be used to trace
|
||||
/// the origin of the authorization or to perform additional validation
|
||||
/// if needed.
|
||||
///
|
||||
/// The validator might be null in cases where the authorization was not
|
||||
/// granted through a standard validation process or if the information
|
||||
/// about the validator is not relevant or available.
|
||||
final AuthValidator? validator;
|
||||
|
||||
/// Basic authorization credentials, if provided.
|
||||
///
|
||||
/// This property holds the parsed basic authorization credentials if they were
|
||||
/// present in the authorization header of the request. If the request did not
|
||||
/// use basic authorization, or if the credentials were not successfully parsed,
|
||||
/// this property will be null.
|
||||
///
|
||||
/// The [AuthBasicCredentials] object typically contains a username and password
|
||||
/// pair extracted from the 'Authorization' header of an HTTP request using the
|
||||
/// Basic authentication scheme.
|
||||
///
|
||||
/// This can be useful for endpoints that support both OAuth 2.0 token-based
|
||||
/// authentication and traditional username/password authentication via Basic Auth.
|
||||
/// If this instance represents the authorization header of a request with basic authorization credentials,
|
||||
/// the parsed credentials will be available in this property. Otherwise, this value is null.
|
||||
final AuthBasicCredentials? credentials;
|
||||
|
||||
/// The list of scopes this authorization has access to.
|
||||
///
|
||||
/// This property represents the set of permissions or access rights granted to this authorization.
|
||||
/// Each [AuthScope] in the list defines a specific area of access or functionality
|
||||
/// that the authorization is allowed to use.
|
||||
///
|
||||
/// If the access token used to create this instance has scopes associated with it,
|
||||
/// those scopes will be available in this list. If no scopes were associated with
|
||||
/// the access token, or if scopes are not being used in the system, this property will be null.
|
||||
///
|
||||
/// Scopes are crucial for implementing fine-grained access control in OAuth 2.0 systems,
|
||||
/// allowing for precise definition of what each authorization is allowed to do.
|
||||
///
|
||||
/// This list can be used in conjunction with the [isAuthorizedForScope] method to check
|
||||
/// if the authorization has access to a specific scope.
|
||||
/// If the access token used to create this instance has scope,
|
||||
/// those scopes will be available here. Otherwise, null.
|
||||
List<AuthScope>? scopes;
|
||||
|
||||
/// Determines if this authorization has access to a specific scope.
|
||||
/// Whether or not this instance has access to a specific scope.
|
||||
///
|
||||
/// This method checks each element in [scopes] for any that gives privileges
|
||||
/// to access [scope].
|
||||
|
|
@ -582,7 +271,7 @@ class Authorization {
|
|||
}
|
||||
}
|
||||
|
||||
/// Represents and manages OAuth 2.0 scopes.
|
||||
/// Instances represent OAuth 2.0 scope.
|
||||
///
|
||||
/// An OAuth 2.0 token may optionally have authorization scopes. An authorization scope provides more granular
|
||||
/// authorization to protected resources. Without authorization scopes, any valid token can pass through an
|
||||
|
|
@ -593,7 +282,7 @@ class Authorization {
|
|||
/// any of the scopes the client provides. Scopes are then granted to the access token. An [Authorizer] may specify
|
||||
/// a one or more required scopes that a token must have to pass to the next controller.
|
||||
class AuthScope {
|
||||
/// Creates an instance of [AuthScope] from a [scopeString].
|
||||
/// Creates an instance of this type from [scopeString].
|
||||
///
|
||||
/// A simple authorization scope string is a single keyword. Valid characters are
|
||||
///
|
||||
|
|
@ -631,27 +320,6 @@ class AuthScope {
|
|||
return scope;
|
||||
}
|
||||
|
||||
/// Parses and creates an [AuthScope] instance from a given scope string.
|
||||
///
|
||||
/// This factory method performs several validation checks on the input [scopeString]:
|
||||
/// 1. Ensures the string is not empty.
|
||||
/// 2. Validates that each character in the string is within the allowed set of characters.
|
||||
/// 3. Parses the string into segments and extracts the modifier (if any).
|
||||
///
|
||||
/// The allowed characters are: A-Za-z0-9!#$%&'`()*+,./:;<=>?@[]^_{|}-
|
||||
///
|
||||
/// If any validation fails, a [FormatException] is thrown with a descriptive error message.
|
||||
///
|
||||
/// After successful validation and parsing, it creates and returns a new [AuthScope] instance.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [scopeString]: The string representation of the scope to parse.
|
||||
///
|
||||
/// Returns:
|
||||
/// A new [AuthScope] instance representing the parsed scope.
|
||||
///
|
||||
/// Throws:
|
||||
/// [FormatException] if the [scopeString] is empty or contains invalid characters.
|
||||
factory AuthScope._parse(String scopeString) {
|
||||
if (scopeString.isEmpty) {
|
||||
throw FormatException(
|
||||
|
|
@ -677,28 +345,16 @@ class AuthScope {
|
|||
return AuthScope._(scopeString, segments, lastModifier);
|
||||
}
|
||||
|
||||
/// Private constructor for creating an [AuthScope] instance.
|
||||
///
|
||||
/// This constructor is used internally by the class to create instances
|
||||
/// after parsing and validating the scope string.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [_scopeString]: The original, unparsed scope string.
|
||||
/// [_segments]: A list of parsed [_AuthScopeSegment] objects representing the scope's segments.
|
||||
/// [_lastModifier]: The modifier of the last segment, if any.
|
||||
///
|
||||
/// This constructor is marked as `const` to allow for compile-time constant instances,
|
||||
/// which can improve performance and memory usage in certain scenarios.
|
||||
const AuthScope._(this._scopeString, this._segments, this._lastModifier);
|
||||
|
||||
/// Represents a special constant for indicating 'any' scope in [AuthServerDelegate.getAllowedScopes].
|
||||
/// Signifies 'any' scope in [AuthServerDelegate.getAllowedScopes].
|
||||
///
|
||||
/// See [AuthServerDelegate.getAllowedScopes] for more details.
|
||||
static const List<AuthScope> any = [
|
||||
AuthScope._("_scope:_constant:_marker", [], null)
|
||||
];
|
||||
|
||||
/// Verifies if the provided scopes fulfill the required scopes.
|
||||
/// Returns true if that [providedScopes] fulfills [requiredScopes].
|
||||
///
|
||||
/// For all [requiredScopes], there must be a scope in [requiredScopes] that meets or exceeds
|
||||
/// that scope for this method to return true. If [requiredScopes] is null, this method
|
||||
|
|
@ -719,97 +375,23 @@ class AuthScope {
|
|||
});
|
||||
}
|
||||
|
||||
/// A cache to store previously created AuthScope instances.
|
||||
///
|
||||
/// This static map serves as a cache to store AuthScope instances that have been
|
||||
/// previously created. The key is the string representation of the scope, and
|
||||
/// the value is the corresponding AuthScope instance.
|
||||
///
|
||||
/// Caching AuthScope instances can improve performance by avoiding repeated
|
||||
/// parsing and object creation for frequently used scopes. When an AuthScope
|
||||
/// is requested with a scope string that already exists in this cache, the
|
||||
/// cached instance is returned instead of creating a new one.
|
||||
static final Map<String, AuthScope> _cache = {};
|
||||
|
||||
/// The original, unparsed scope string.
|
||||
///
|
||||
/// This private field stores the complete scope string as it was originally provided
|
||||
/// when creating the AuthScope instance. It represents the full, unmodified scope
|
||||
/// including all segments and modifiers.
|
||||
///
|
||||
/// This string is used for caching purposes and when converting the AuthScope
|
||||
/// back to its string representation (e.g., in the toString() method).
|
||||
final String _scopeString;
|
||||
|
||||
/// Returns an iterable of individual segments of this AuthScope instance.
|
||||
/// Individual segments, separated by `:` character, of this instance.
|
||||
///
|
||||
/// Will always have a length of at least 1.
|
||||
Iterable<String?> get segments => _segments.map((s) => s.name);
|
||||
|
||||
/// Returns the modifier of this scope, if it exists.
|
||||
/// The modifier of this scope, if it exists.
|
||||
///
|
||||
/// The modifier is an optional component of an AuthScope that provides additional
|
||||
/// specification or restriction to the scope. It is typically the last part of a
|
||||
/// scope string, following a dot (.) after the last segment.
|
||||
///
|
||||
/// For example, in the scope "user:profile.readonly", "readonly" is the modifier.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [String] representing the modifier if one exists, or null if this AuthScope
|
||||
/// does not have a modifier.
|
||||
///
|
||||
/// This getter provides access to the private [_lastModifier] field, allowing
|
||||
/// external code to check for the presence and value of a modifier without
|
||||
/// directly accessing the internal state of the AuthScope.
|
||||
/// If this instance does not have a modifier, returns null.
|
||||
String? get modifier => _lastModifier;
|
||||
|
||||
/// List of segments that make up this AuthScope.
|
||||
///
|
||||
/// This private field stores the parsed segments of the scope string as a list of
|
||||
/// [_AuthScopeSegment] objects. Each segment represents a part of the scope,
|
||||
/// separated by colons in the original scope string.
|
||||
///
|
||||
/// For example, for a scope string "user:profile:read", this list would contain
|
||||
/// three _AuthScopeSegment objects representing "user", "profile", and "read"
|
||||
/// respectively.
|
||||
///
|
||||
/// This list is used internally for scope comparisons and validations.
|
||||
final List<_AuthScopeSegment> _segments;
|
||||
|
||||
/// The modifier of the last segment in this AuthScope.
|
||||
///
|
||||
/// This private field stores the modifier of the last segment in the AuthScope,
|
||||
/// if one exists. A modifier provides additional specification or restriction
|
||||
/// to a scope and is typically the part following a dot (.) in the last segment
|
||||
/// of a scope string.
|
||||
///
|
||||
/// For example, in the scope "user:profile.readonly", "readonly" would be stored
|
||||
/// in this field.
|
||||
///
|
||||
/// The value is null if the AuthScope does not have a modifier in its last segment.
|
||||
final String? _lastModifier;
|
||||
|
||||
/// Parses the given scope string into a list of [_AuthScopeSegment] objects.
|
||||
///
|
||||
/// This method performs the following steps:
|
||||
/// 1. Checks if the input string is empty and throws a [FormatException] if it is.
|
||||
/// 2. Splits the string by ':' and creates [_AuthScopeSegment] objects for each segment.
|
||||
/// 3. Validates each segment, ensuring:
|
||||
/// - Only the last segment can have a modifier.
|
||||
/// - There are no empty segments.
|
||||
/// - There are no leading or trailing colons.
|
||||
///
|
||||
/// If any validation fails, a [FormatException] is thrown with a descriptive error message
|
||||
/// and the position in the string where the error occurred.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [scopeString]: The string representation of the scope to parse.
|
||||
///
|
||||
/// Returns:
|
||||
/// A list of [_AuthScopeSegment] objects representing the parsed segments of the scope.
|
||||
///
|
||||
/// Throws:
|
||||
/// [FormatException] if the [scopeString] is empty or contains invalid segments.
|
||||
static List<_AuthScopeSegment> _parseSegments(String scopeString) {
|
||||
if (scopeString.isEmpty) {
|
||||
throw FormatException(
|
||||
|
|
@ -853,7 +435,7 @@ class AuthScope {
|
|||
return elements;
|
||||
}
|
||||
|
||||
/// Determines if this [AuthScope] is a subset of or equal to the [incomingScope].
|
||||
/// Whether or not this instance is a subset or equal to [incomingScope].
|
||||
///
|
||||
/// The scope `users:posts` is a subset of `users`.
|
||||
///
|
||||
|
|
@ -895,42 +477,16 @@ class AuthScope {
|
|||
}
|
||||
|
||||
/// Alias of [isSubsetOrEqualTo].
|
||||
///
|
||||
/// This method is deprecated and will be removed in a future version.
|
||||
/// Use [isSubsetOrEqualTo] instead.
|
||||
///
|
||||
/// Determines if this [AuthScope] allows the [incomingScope].
|
||||
/// It is equivalent to calling [isSubsetOrEqualTo] with the same argument.
|
||||
///
|
||||
/// [incomingScope]: The AuthScope to compare against this instance.
|
||||
///
|
||||
/// Returns true if this AuthScope is a subset of or equal to the [incomingScope],
|
||||
/// false otherwise.
|
||||
@Deprecated('Use AuthScope.isSubsetOrEqualTo() instead')
|
||||
bool allowsScope(AuthScope incomingScope) => isSubsetOrEqualTo(incomingScope);
|
||||
|
||||
/// Checks if this AuthScope is a subset of or equal to the given scope string.
|
||||
/// String variant of [isSubsetOrEqualTo].
|
||||
///
|
||||
/// Parses an instance of this type from [scopeString] and invokes
|
||||
/// [isSubsetOrEqualTo].
|
||||
bool allows(String scopeString) => isSubsetOrEqualTo(AuthScope(scopeString));
|
||||
|
||||
/// Determines if this [AuthScope] is exactly the same as the given [scope].
|
||||
///
|
||||
/// This method compares each segment and modifier of both scopes to ensure they are identical.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [scope]: The [AuthScope] to compare against this instance.
|
||||
///
|
||||
/// Returns:
|
||||
/// [bool]: true if both scopes are exactly the same, false otherwise.
|
||||
///
|
||||
/// The comparison is performed as follows:
|
||||
/// 1. Iterates through each segment of both scopes simultaneously.
|
||||
/// 2. If the given scope has fewer segments, returns false.
|
||||
/// 3. Compares the name and modifier of each segment.
|
||||
/// 4. If any segment's name or modifier doesn't match, returns false.
|
||||
/// 5. If all segments match and both scopes have the same number of segments, returns true.
|
||||
/// Whether or not two scopes are exactly the same.
|
||||
bool isExactlyScope(AuthScope scope) {
|
||||
final incomingIterator = scope._segments.iterator;
|
||||
for (final segment in _segments) {
|
||||
|
|
@ -950,44 +506,18 @@ class AuthScope {
|
|||
return true;
|
||||
}
|
||||
|
||||
/// Checks if this AuthScope is exactly the same as the given scope string.
|
||||
/// String variant of [isExactlyScope].
|
||||
///
|
||||
/// Parses an instance of this type from [scopeString] and invokes [isExactlyScope].
|
||||
bool isExactly(String scopeString) {
|
||||
return isExactlyScope(AuthScope(scopeString));
|
||||
}
|
||||
|
||||
/// Returns a string representation of this AuthScope.
|
||||
///
|
||||
/// This method overrides the default [Object.toString] method to provide
|
||||
/// a string representation of the AuthScope instance. It returns the
|
||||
/// original, unparsed scope string that was used to create this AuthScope.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [String] representing the complete scope, including all segments
|
||||
/// and modifiers, exactly as it was originally provided.
|
||||
///
|
||||
/// Example:
|
||||
/// final scope = AuthScope('user:profile.readonly');
|
||||
/// print(scope.toString()); // Outputs: 'user:profile.readonly'
|
||||
@override
|
||||
String toString() => _scopeString;
|
||||
}
|
||||
|
||||
/// Represents a segment of an AuthScope.
|
||||
///
|
||||
/// An AuthScope can be composed of one or more segments, where each segment
|
||||
/// may have a name and an optional modifier. This class parses and stores
|
||||
/// the components of a single segment.
|
||||
class _AuthScopeSegment {
|
||||
/// Constructs an AuthScopeSegment from the given [segment] string.
|
||||
///
|
||||
/// The [segment] string is expected to be in the format "name.modifier" or "name".
|
||||
/// If a modifier is present, it is stored in the [modifier] field. If not, [modifier]
|
||||
/// remains null. The [name] field always contains the name of the segment.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [segment]: A [String] representing the segment, which may include a modifier.
|
||||
_AuthScopeSegment(String segment) {
|
||||
final split = segment.split(".");
|
||||
if (split.length == 2) {
|
||||
|
|
@ -998,42 +528,9 @@ class _AuthScopeSegment {
|
|||
}
|
||||
}
|
||||
|
||||
/// The name of the segment.
|
||||
///
|
||||
/// This property represents the main part of the segment before any modifier.
|
||||
/// For example, in the segment "user.readonly", "user" would be the name.
|
||||
///
|
||||
/// This value can be null if the segment is empty or malformed.
|
||||
String? name;
|
||||
|
||||
/// The modifier of the segment, if present.
|
||||
///
|
||||
/// This property represents the optional part of the segment after the name,
|
||||
/// if a modifier is specified. For example, in the segment "user.readonly",
|
||||
/// "readonly" would be the modifier.
|
||||
///
|
||||
/// If no modifier is present in the segment, this value is null.
|
||||
String? modifier;
|
||||
|
||||
/// Returns a string representation of this AuthScopeSegment.
|
||||
///
|
||||
/// This method overrides the default [Object.toString] method to provide
|
||||
/// a string representation of the AuthScopeSegment instance.
|
||||
///
|
||||
/// If the segment has a modifier, it returns the name and modifier
|
||||
/// separated by a dot (e.g., "name.modifier").
|
||||
/// If there's no modifier, it returns just the name.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [String] representing the complete segment, including the
|
||||
/// modifier if present.
|
||||
///
|
||||
/// Example:
|
||||
/// final segment = _AuthScopeSegment('user.readonly');
|
||||
/// print(segment.toString()); // Outputs: 'user.readonly'
|
||||
///
|
||||
/// final segmentNoModifier = _AuthScopeSegment('user');
|
||||
/// print(segmentNoModifier.toString()); // Outputs: 'user'
|
||||
@override
|
||||
String toString() {
|
||||
if (modifier == null) {
|
||||
|
|
|
|||
|
|
@ -1,16 +1,7 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
import 'package:protevus_auth/auth.dart';
|
||||
|
||||
/// Defines the interface for a Resource Owner in OAuth 2.0 authentication.
|
||||
/// The properties of an OAuth 2.0 Resource Owner.
|
||||
///
|
||||
/// Your application's 'user' type must implement the methods declared in this interface. [AuthServer] can
|
||||
/// validate the credentials of a [ResourceOwner] to grant authorization codes and access tokens on behalf of that
|
||||
|
|
@ -18,59 +9,20 @@ import 'package:protevus_auth/auth.dart';
|
|||
abstract class ResourceOwner {
|
||||
/// The username of the resource owner.
|
||||
///
|
||||
/// This property represents the unique identifier for a resource owner, typically used for authentication purposes.
|
||||
/// It must be unique among all resource owners in the system. Often, this value is an email address.
|
||||
///
|
||||
/// The username is used by authenticating users to identify their account when logging in or performing
|
||||
/// other authentication-related actions.
|
||||
///
|
||||
/// This property is nullable, which means it can be null in some cases, such as when creating a new
|
||||
/// resource owner instance before setting the username.
|
||||
/// This value must be unique amongst all resource owners. It is often an email address. This value
|
||||
/// is used by authenticating users to identify their account.
|
||||
String? username;
|
||||
|
||||
/// The hashed password of this instance.
|
||||
///
|
||||
/// This property stores the password of the resource owner in a hashed format.
|
||||
/// Hashing is a one-way process that converts the plain text password into a
|
||||
/// fixed-length string of characters, which is more secure to store than the
|
||||
/// original password.
|
||||
///
|
||||
/// The hashed password is used for password verification during authentication
|
||||
/// without storing the actual password. This enhances security by ensuring
|
||||
/// that even if the database is compromised, the original passwords remain
|
||||
/// unknown.
|
||||
///
|
||||
/// This property is nullable, allowing for cases where a password might not
|
||||
/// be set or required for certain types of resource owners.
|
||||
String? hashedPassword;
|
||||
|
||||
/// The salt used in the hashing process for [hashedPassword].
|
||||
///
|
||||
/// A salt is a random string that is added to the password before hashing,
|
||||
/// which adds an extra layer of security to the hashed password. It helps
|
||||
/// protect against rainbow table attacks and ensures that even if two users
|
||||
/// have the same password, their hashed passwords will be different.
|
||||
///
|
||||
/// This property is nullable to accommodate cases where a salt might not be
|
||||
/// used or stored separately from the hashed password.
|
||||
/// The salt the [hashedPassword] was hashed with.
|
||||
String? salt;
|
||||
|
||||
/// A unique identifier of this resource owner.
|
||||
///
|
||||
/// This property represents a unique identifier for the resource owner, typically
|
||||
/// used in authentication and authorization processes. The [AuthServer] uses this
|
||||
/// identifier to associate authorization codes and access tokens with the specific
|
||||
/// resource owner.
|
||||
///
|
||||
/// The identifier is of type [int] and is nullable, allowing for cases where an ID
|
||||
/// might not be assigned yet (e.g., when creating a new resource owner instance).
|
||||
///
|
||||
/// It's crucial to ensure that this ID remains unique across all resource owners
|
||||
/// in the system to maintain the integrity of the authentication and authorization
|
||||
/// processes.
|
||||
///
|
||||
/// This getter method should be implemented to return the unique identifier of
|
||||
/// the resource owner.
|
||||
/// This unique identifier is used by [AuthServer] to associate authorization codes and access tokens with
|
||||
/// this resource owner.
|
||||
int? get id;
|
||||
}
|
||||
|
||||
|
|
@ -81,23 +33,8 @@ abstract class ResourceOwner {
|
|||
///
|
||||
/// Prefer to use `ManagedAuthDelegate` from 'package:conduit_core/managed_auth.dart' instead of implementing this interface;
|
||||
/// there are important details to consider and test when implementing this interface.
|
||||
///
|
||||
/// This abstract class defines the contract for implementing an authentication and authorization system.
|
||||
/// It provides methods for managing resource owners, clients, tokens, and authorization codes.
|
||||
/// Implementations of this class are responsible for handling the storage, retrieval, and management
|
||||
/// of these entities, as well as customizing certain behaviors of the authentication process.
|
||||
///
|
||||
/// Key responsibilities include:
|
||||
/// - Managing resource owners (users)
|
||||
/// - Handling client applications
|
||||
/// - Storing and retrieving access and refresh tokens
|
||||
/// - Managing authorization codes
|
||||
/// - Customizing token formats and allowed scopes
|
||||
///
|
||||
/// Each method in this class corresponds to a specific operation in the OAuth 2.0 flow,
|
||||
/// allowing for a flexible and extensible authentication system.
|
||||
abstract class AuthServerDelegate {
|
||||
/// Retrieves a [ResourceOwner] based on the provided [username].
|
||||
/// Must return a [ResourceOwner] for a [username].
|
||||
///
|
||||
/// This method must return an instance of [ResourceOwner] if one exists for [username]. Otherwise, it must return null.
|
||||
///
|
||||
|
|
@ -106,19 +43,19 @@ abstract class AuthServerDelegate {
|
|||
/// [server] is the [AuthServer] invoking this method.
|
||||
FutureOr<ResourceOwner?> getResourceOwner(AuthServer server, String username);
|
||||
|
||||
/// Stores a new [AuthClient] in the system.
|
||||
/// Must store [client].
|
||||
///
|
||||
/// [client] must be returned by [getClient] after this method has been invoked, and until (if ever)
|
||||
/// [removeClient] is invoked.
|
||||
FutureOr addClient(AuthServer server, AuthClient client);
|
||||
|
||||
/// Retrieves an [AuthClient] based on the provided client ID.
|
||||
/// Must return [AuthClient] for a client ID.
|
||||
///
|
||||
/// This method must return an instance of [AuthClient] if one exists for [clientID]. Otherwise, it must return null.
|
||||
/// [server] is the [AuthServer] requesting the [AuthClient].
|
||||
FutureOr<AuthClient?> getClient(AuthServer server, String clientID);
|
||||
|
||||
/// Removes an [AuthClient] for a given client ID.
|
||||
/// Removes an [AuthClient] for a client ID.
|
||||
///
|
||||
/// This method must delete the [AuthClient] for [clientID]. Subsequent requests to this
|
||||
/// instance for [getClient] must return null after this method completes. If there is no
|
||||
|
|
@ -127,7 +64,7 @@ abstract class AuthServerDelegate {
|
|||
/// [server] is the [AuthServer] requesting the [AuthClient].
|
||||
FutureOr removeClient(AuthServer server, String clientID);
|
||||
|
||||
/// Retrieves an [AuthToken] based on either its access token or refresh token.
|
||||
/// Returns a [AuthToken] searching by its access token or refresh token.
|
||||
///
|
||||
/// Exactly one of [byAccessToken] and [byRefreshToken] may be non-null, if not, this method must throw an error.
|
||||
///
|
||||
|
|
@ -143,12 +80,12 @@ abstract class AuthServerDelegate {
|
|||
String? byRefreshToken,
|
||||
});
|
||||
|
||||
/// Deletes all [AuthToken]s and [AuthCode]s associated with a specific [ResourceOwner].
|
||||
/// This method must delete all [AuthToken] and [AuthCode]s for a [ResourceOwner].
|
||||
///
|
||||
/// [server] is the requesting [AuthServer]. [resourceOwnerID] is the [ResourceOwner.id].
|
||||
FutureOr removeTokens(AuthServer server, int resourceOwnerID);
|
||||
|
||||
/// Deletes an [AuthToken] that was granted by a specific [AuthCode].
|
||||
/// Must delete a [AuthToken] granted by [grantedByCode].
|
||||
///
|
||||
/// If an [AuthToken] has been granted by exchanging [AuthCode], that token must be revoked
|
||||
/// and can no longer be used to authorize access to a resource. [grantedByCode] should
|
||||
|
|
@ -157,7 +94,7 @@ abstract class AuthServerDelegate {
|
|||
/// This method is invoked when attempting to exchange an authorization code that has already granted a token.
|
||||
FutureOr removeToken(AuthServer server, AuthCode grantedByCode);
|
||||
|
||||
/// Stores an [AuthToken] in the system.
|
||||
/// Must store [token].
|
||||
///
|
||||
/// [token] must be stored such that it is accessible from [getToken], and until it is either
|
||||
/// revoked via [removeToken] or [removeTokens], or until it has expired and can reasonably
|
||||
|
|
@ -170,7 +107,7 @@ abstract class AuthServerDelegate {
|
|||
/// is null.
|
||||
FutureOr addToken(AuthServer server, AuthToken token, {AuthCode? issuedFrom});
|
||||
|
||||
/// Updates an existing [AuthToken] with new values.
|
||||
/// Must update [AuthToken] with [newAccessToken, [newIssueDate, [newExpirationDate].
|
||||
///
|
||||
/// This method must must update an existing [AuthToken], found by [oldAccessToken],
|
||||
/// with the values [newAccessToken], [newIssueDate] and [newExpirationDate].
|
||||
|
|
@ -185,23 +122,23 @@ abstract class AuthServerDelegate {
|
|||
DateTime? newExpirationDate,
|
||||
);
|
||||
|
||||
/// Stores an [AuthCode] in the system.
|
||||
/// Must store [code].
|
||||
///
|
||||
/// [code] must be accessible until its expiration date.
|
||||
FutureOr addCode(AuthServer server, AuthCode code);
|
||||
|
||||
/// Retrieves an [AuthCode] based on its identifying code.
|
||||
/// Must return [AuthCode] for its identifiying [code].
|
||||
///
|
||||
/// This must return an instance of [AuthCode] where [AuthCode.code] matches [code].
|
||||
/// Return null if no matching code.
|
||||
FutureOr<AuthCode?> getCode(AuthServer server, String code);
|
||||
|
||||
/// Removes an [AuthCode] from the system based on its identifying code.
|
||||
/// Must remove [AuthCode] identified by [code].
|
||||
///
|
||||
/// The [AuthCode.code] matching [code] must be deleted and no longer accessible.
|
||||
FutureOr removeCode(AuthServer server, String? code);
|
||||
|
||||
/// Returns a list of allowed scopes for a given [ResourceOwner].
|
||||
/// Returns list of allowed scopes for a given [ResourceOwner].
|
||||
///
|
||||
/// Subclasses override this method to return a list of [AuthScope]s based on some attribute(s) of an [ResourceOwner].
|
||||
/// That [ResourceOwner] is then restricted to only those scopes, even if the authenticating client would allow other scopes
|
||||
|
|
|
|||
|
|
@ -1,12 +1,3 @@
|
|||
/*
|
||||
* This file is part of the Protevus Platform.
|
||||
*
|
||||
* (C) Protevus <developers@protevus.com>
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
import 'dart:async';
|
||||
|
||||
import 'package:protevus_openapi/documentable.dart';
|
||||
|
|
@ -14,14 +5,14 @@ import 'package:protevus_auth/auth.dart';
|
|||
import 'package:protevus_http/http.dart';
|
||||
import 'package:protevus_openapi/v3.dart';
|
||||
|
||||
/// A mixin that defines the interface for validating authorization data.
|
||||
/// Instances that implement this type can be used by an [Authorizer] to determine authorization of a request.
|
||||
///
|
||||
/// When an [Authorizer] processes a [Request], it invokes [validate], passing in the parsed Authorization
|
||||
/// header of the [Request].
|
||||
///
|
||||
/// [AuthServer] implements this interface.
|
||||
mixin AuthValidator {
|
||||
/// Validates authorization data and returns an [Authorization] if valid.
|
||||
/// Returns an [Authorization] if [authorizationData] is valid.
|
||||
///
|
||||
/// This method is invoked by [Authorizer] to validate the Authorization header of a request. [authorizationData]
|
||||
/// is the parsed contents of the Authorization header, while [parser] is the object that parsed the header.
|
||||
|
|
@ -37,7 +28,7 @@ mixin AuthValidator {
|
|||
List<AuthScope>? requiredScope,
|
||||
});
|
||||
|
||||
/// Provides [APISecurityRequirement]s for the given [authorizer].
|
||||
/// Provide [APISecurityRequirement]s for [authorizer].
|
||||
///
|
||||
/// An [Authorizer] that adds security requirements to operations will invoke this method to allow this validator to define those requirements.
|
||||
/// The [Authorizer] must provide the [context] it was given to document the operations, itself and optionally a list of [scopes] required to pass it.
|
||||
|
|
|
|||
|
|
@ -13,28 +13,7 @@ import 'dart:mirrors';
|
|||
import 'package:protevus_config/config.dart';
|
||||
import 'package:protevus_runtime/runtime.dart';
|
||||
|
||||
/// A compiler class for configurations in the Protevus Platform.
|
||||
///
|
||||
/// This class extends the [Compiler] class and provides functionality to
|
||||
/// compile configuration-related data and modify package files.
|
||||
///
|
||||
/// The [compile] method creates a map of configuration names to their
|
||||
/// corresponding [ConfigurationRuntimeImpl] instances by scanning for
|
||||
/// subclasses of [Configuration] in the given [MirrorContext].
|
||||
///
|
||||
/// The [deflectPackage] method modifies the "conduit_config.dart" file in the
|
||||
/// destination directory by removing a specific export statement.
|
||||
class ConfigurationCompiler extends Compiler {
|
||||
/// Compiles configuration data from the given [MirrorContext].
|
||||
///
|
||||
/// This method scans the [context] for all subclasses of [Configuration]
|
||||
/// and creates a map where:
|
||||
/// - The keys are the names of these subclasses (as strings)
|
||||
/// - The values are instances of [ConfigurationRuntimeImpl] created from
|
||||
/// the corresponding subclass
|
||||
///
|
||||
/// Returns a [Map<String, Object>] where each entry represents a
|
||||
/// configuration class and its runtime implementation.
|
||||
@override
|
||||
Map<String, Object> compile(MirrorContext context) {
|
||||
return Map.fromEntries(
|
||||
|
|
@ -47,26 +26,15 @@ class ConfigurationCompiler extends Compiler {
|
|||
);
|
||||
}
|
||||
|
||||
/// Modifies the package file by removing a specific export statement.
|
||||
///
|
||||
/// This method performs the following steps:
|
||||
/// 1. Locates the "config.dart" file in the "lib/" directory of the [destinationDirectory].
|
||||
/// 2. Reads the contents of the file.
|
||||
/// 3. Removes the line "export 'package:protevus_config/src/compiler.dart';" from the file contents.
|
||||
/// 4. Writes the modified contents back to the file.
|
||||
///
|
||||
/// This operation is typically used to adjust the exported modules in the compiled package.
|
||||
///
|
||||
/// [destinationDirectory] is the directory where the package files are located.
|
||||
@override
|
||||
void deflectPackage(Directory destinationDirectory) {
|
||||
final libFile = File.fromUri(
|
||||
destinationDirectory.uri.resolve("lib/").resolve("config.dart"),
|
||||
destinationDirectory.uri.resolve("lib/").resolve("conduit_config.dart"),
|
||||
);
|
||||
final contents = libFile.readAsStringSync();
|
||||
libFile.writeAsStringSync(
|
||||
contents.replaceFirst(
|
||||
"export 'package:protevus_config/src/compiler.dart';", ""),
|
||||
"export 'package:conduit_config/src/compiler.dart';", ""),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -14,90 +14,17 @@ import 'package:protevus_runtime/runtime.dart';
|
|||
import 'package:meta/meta.dart';
|
||||
import 'package:yaml/yaml.dart';
|
||||
|
||||
/// A base class for configuration management in Dart applications.
|
||||
///
|
||||
/// [Configuration] provides a framework for reading and parsing YAML-based
|
||||
/// configuration files or strings. It offers various constructors to create
|
||||
/// configuration objects from different sources (maps, strings, or files),
|
||||
/// and includes methods for decoding and validating configuration data.
|
||||
///
|
||||
/// Key features:
|
||||
/// - Supports creating configurations from YAML strings, files, or maps
|
||||
/// - Provides a runtime context for configuration-specific operations
|
||||
/// - Includes a default decoding mechanism that can be overridden
|
||||
/// - Offers a validation method to ensure all required fields are present
|
||||
/// - Allows for environment variable substitution in configuration values
|
||||
///
|
||||
/// Subclasses of [Configuration] should implement specific configuration
|
||||
/// structures by defining properties that correspond to expected YAML keys.
|
||||
/// The [decode] and [validate] methods can be overridden to provide custom
|
||||
/// behavior for complex configuration scenarios.
|
||||
///
|
||||
/// Example usage:
|
||||
/// ```dart
|
||||
/// class MyConfig extends Configuration {
|
||||
/// late String apiKey;
|
||||
/// int port = 8080;
|
||||
///
|
||||
/// @override
|
||||
/// void validate() {
|
||||
/// super.validate();
|
||||
/// if (port < 1000 || port > 65535) {
|
||||
/// throw ConfigurationException(this, "Invalid port number");
|
||||
/// }
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// final config = MyConfig.fromFile(File('config.yaml'));
|
||||
/// ```
|
||||
/// Subclasses of [Configuration] read YAML strings and files, assigning values from the YAML document to properties
|
||||
/// of an instance of this type.
|
||||
abstract class Configuration {
|
||||
/// Default constructor for the Configuration class.
|
||||
///
|
||||
/// This constructor creates a new instance of the Configuration class
|
||||
/// without any initial configuration data. It can be used as a starting
|
||||
/// point for creating custom configurations, which can then be populated
|
||||
/// using other methods or by setting properties directly.
|
||||
/// Default constructor.
|
||||
Configuration();
|
||||
|
||||
/// Creates a [Configuration] instance from a given map.
|
||||
///
|
||||
/// This constructor takes a [Map] with dynamic keys and values, converts
|
||||
/// all keys to strings, and then decodes the resulting map into the
|
||||
/// configuration properties. This is useful when you have configuration
|
||||
/// data already in a map format, possibly from a non-YAML source.
|
||||
///
|
||||
/// [map] The input map containing configuration data. Keys will be
|
||||
/// converted to strings, while values remain as their original types.
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// final configMap = {'key1': 'value1', 'key2': 42};
|
||||
/// final config = MyConfiguration.fromMap(configMap);
|
||||
/// ```
|
||||
Configuration.fromMap(Map<dynamic, dynamic> map) {
|
||||
decode(map.map<String, dynamic>((k, v) => MapEntry(k.toString(), v)));
|
||||
}
|
||||
|
||||
/// Creates a [Configuration] instance from a YAML string.
|
||||
///
|
||||
/// This constructor takes a [String] containing YAML content, parses it into
|
||||
/// a map, and then decodes the resulting map into the configuration properties.
|
||||
/// It's useful when you have configuration data as a YAML string, perhaps
|
||||
/// loaded from a file or received from an API.
|
||||
///
|
||||
/// [contents] A string containing valid YAML data. This will be parsed and
|
||||
/// used to populate the configuration properties.
|
||||
///
|
||||
/// Throws a [YamlException] if the YAML parsing fails.
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// final yamlString = '''
|
||||
/// api_key: abc123
|
||||
/// port: 8080
|
||||
/// ''';
|
||||
/// final config = MyConfiguration.fromString(yamlString);
|
||||
/// ```
|
||||
/// [contents] must be YAML.
|
||||
Configuration.fromString(String contents) {
|
||||
final yamlMap = loadYaml(contents) as Map<dynamic, dynamic>?;
|
||||
final map =
|
||||
|
|
@ -105,29 +32,15 @@ abstract class Configuration {
|
|||
decode(map);
|
||||
}
|
||||
|
||||
/// Creates a [Configuration] instance from a YAML file.
|
||||
/// Opens a file and reads its string contents into this instance's properties.
|
||||
///
|
||||
/// [file] must contain valid YAML data.
|
||||
Configuration.fromFile(File file) : this.fromString(file.readAsStringSync());
|
||||
|
||||
/// Returns the [ConfigurationRuntime] associated with the current instance's runtime type.
|
||||
///
|
||||
/// This getter retrieves the [ConfigurationRuntime] from the [RuntimeContext.current] map,
|
||||
/// using the runtime type of the current instance as the key. The retrieved value
|
||||
/// is then cast to [ConfigurationRuntime].
|
||||
///
|
||||
/// This is typically used internally to access runtime-specific configuration
|
||||
/// operations and validations.
|
||||
///
|
||||
/// Returns:
|
||||
/// The [ConfigurationRuntime] associated with this configuration's type.
|
||||
///
|
||||
/// Throws:
|
||||
/// A runtime exception if the retrieved value cannot be cast to [ConfigurationRuntime].
|
||||
ConfigurationRuntime get _runtime =>
|
||||
RuntimeContext.current[runtimeType] as ConfigurationRuntime;
|
||||
|
||||
/// Decodes the given [value] and populates the properties of this configuration instance.
|
||||
/// Ingests [value] into the properties of this type.
|
||||
///
|
||||
/// Override this method to provide decoding behavior other than the default behavior.
|
||||
void decode(dynamic value) {
|
||||
|
|
@ -145,8 +58,7 @@ abstract class Configuration {
|
|||
|
||||
/// Validates this configuration.
|
||||
///
|
||||
/// This method is called automatically after the configuration is decoded. It performs
|
||||
/// validation checks on the configuration data to ensure its integrity and correctness.
|
||||
/// By default, ensures all required keys are non-null.
|
||||
///
|
||||
/// Override this method to perform validations on input data. Throw [ConfigurationException]
|
||||
/// for invalid data.
|
||||
|
|
@ -155,24 +67,6 @@ abstract class Configuration {
|
|||
_runtime.validate(this);
|
||||
}
|
||||
|
||||
/// Retrieves an environment variable value or returns the original value.
|
||||
///
|
||||
/// This method checks if the given [value] is a string that starts with '$'.
|
||||
/// If so, it interprets the rest of the string as an environment variable name
|
||||
/// and attempts to retrieve its value from the system environment.
|
||||
///
|
||||
/// If the environment variable exists, its value is returned.
|
||||
/// If the environment variable does not exist, null is returned.
|
||||
/// If the [value] is not a string starting with '$', the original [value] is returned unchanged.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [value]: The value to check. Can be of any type.
|
||||
///
|
||||
/// Returns:
|
||||
/// - The value of the environment variable if [value] is a string starting with '$'
|
||||
/// and the corresponding environment variable exists.
|
||||
/// - null if [value] is a string starting with '$' but the environment variable doesn't exist.
|
||||
/// - The original [value] if it's not a string starting with '$'.
|
||||
static dynamic getEnvironmentOrValue(dynamic value) {
|
||||
if (value is String && value.startsWith(r"$")) {
|
||||
final envKey = value.substring(1);
|
||||
|
|
@ -186,72 +80,10 @@ abstract class Configuration {
|
|||
}
|
||||
}
|
||||
|
||||
/// An abstract class representing the runtime behavior for configuration objects.
|
||||
///
|
||||
/// This class provides methods for decoding and validating configuration objects,
|
||||
/// as well as a utility method for handling exceptions during the decoding process.
|
||||
///
|
||||
/// Implementations of this class should provide concrete logic for decoding
|
||||
/// configuration data from input maps and validating the resulting configuration objects.
|
||||
///
|
||||
/// The [tryDecode] method offers a standardized way to handle exceptions that may occur
|
||||
/// during the decoding process, wrapping them in appropriate [ConfigurationException]s
|
||||
/// with detailed key paths for easier debugging.
|
||||
abstract class ConfigurationRuntime {
|
||||
/// Decodes the input map and populates the given configuration object.
|
||||
///
|
||||
/// This method is responsible for parsing the input map and setting the
|
||||
/// corresponding values in the configuration object. It should handle
|
||||
/// type conversions, nested structures, and any specific logic required
|
||||
/// for populating the configuration.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [configuration]: The Configuration object to be populated with decoded values.
|
||||
/// [input]: A Map containing the raw configuration data to be decoded.
|
||||
///
|
||||
/// Implementations of this method should handle potential errors gracefully,
|
||||
/// possibly by throwing ConfigurationException for invalid or missing data.
|
||||
void decode(Configuration configuration, Map input);
|
||||
|
||||
/// Validates the given configuration object.
|
||||
///
|
||||
/// This method is responsible for performing validation checks on the
|
||||
/// provided configuration object. It should ensure that all required
|
||||
/// fields are present and that the values meet any specific criteria
|
||||
/// or constraints defined for the configuration.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [configuration]: The Configuration object to be validated.
|
||||
///
|
||||
/// Implementations of this method should throw a [ConfigurationException]
|
||||
/// if any validation errors are encountered, providing clear and specific
|
||||
/// error messages to aid in debugging and resolution of configuration issues.
|
||||
void validate(Configuration configuration);
|
||||
|
||||
/// Attempts to decode a configuration property and handles exceptions.
|
||||
///
|
||||
/// This method provides a standardized way to handle exceptions that may occur
|
||||
/// during the decoding process of a configuration property. It wraps the decoding
|
||||
/// logic in a try-catch block and transforms various exceptions into appropriate
|
||||
/// [ConfigurationException]s with detailed key paths for easier debugging.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [configuration]: The Configuration object being decoded.
|
||||
/// [name]: The name of the property being decoded.
|
||||
/// [decode]: A function that performs the actual decoding logic.
|
||||
///
|
||||
/// Returns:
|
||||
/// The result of the [decode] function if successful.
|
||||
///
|
||||
/// Throws:
|
||||
/// [ConfigurationException]:
|
||||
/// - If a [ConfigurationException] is caught, it's re-thrown with an updated key path.
|
||||
/// - If an [IntermediateException] is caught, it's transformed into a [ConfigurationException]
|
||||
/// with appropriate error details.
|
||||
/// - For any other exception, a new [ConfigurationException] is thrown with the exception message.
|
||||
///
|
||||
/// This method is particularly useful for maintaining a consistent error handling
|
||||
/// approach across different configuration properties and types.
|
||||
dynamic tryDecode(
|
||||
Configuration configuration,
|
||||
String name,
|
||||
|
|
@ -302,40 +134,18 @@ abstract class ConfigurationRuntime {
|
|||
}
|
||||
}
|
||||
|
||||
/// Enumerates the possible options for a configuration item property's optionality.
|
||||
///
|
||||
/// This enum is used to specify whether a configuration property is required or optional
|
||||
/// when parsing configuration data. It helps in determining how to handle missing keys
|
||||
/// in the source YAML configuration.
|
||||
/// Possible options for a configuration item property's optionality.
|
||||
enum ConfigurationItemAttributeType {
|
||||
/// Indicates that a configuration property is required.
|
||||
///
|
||||
/// When a configuration property is marked as [required], it means that
|
||||
/// the corresponding key must be present in the source YAML configuration.
|
||||
/// If the key is missing, an exception will be thrown during the parsing
|
||||
/// or validation process.
|
||||
///
|
||||
/// This helps ensure that all necessary configuration values are provided
|
||||
/// and reduces the risk of runtime errors due to missing configuration data.
|
||||
/// [Configuration] properties marked as [required] will throw an exception
|
||||
/// if their source YAML doesn't contain a matching key.
|
||||
required,
|
||||
|
||||
/// Indicates that a configuration property is optional.
|
||||
///
|
||||
/// When a configuration property is marked as [optional], it means that
|
||||
/// the corresponding key can be omitted from the source YAML configuration
|
||||
/// without causing an error. If the key is missing, the property will be
|
||||
/// silently ignored during the parsing process.
|
||||
///
|
||||
/// This allows for more flexible configuration structures where some
|
||||
/// properties are not mandatory and can be omitted without affecting
|
||||
/// the overall functionality of the configuration.
|
||||
///
|
||||
/// [Configuration] properties marked as [optional] will be silently ignored
|
||||
/// if their source YAML doesn't contain a matching key.
|
||||
optional
|
||||
}
|
||||
|
||||
/// Represents an attribute for configuration item properties.
|
||||
/// [Configuration] properties may be attributed with these.
|
||||
///
|
||||
/// **NOTICE**: This will be removed in version 2.0.0.
|
||||
/// To signify required or optional config you could do:
|
||||
|
|
@ -394,83 +204,14 @@ const ConfigurationItemAttribute requiredConfiguration =
|
|||
const ConfigurationItemAttribute optionalConfiguration =
|
||||
ConfigurationItemAttribute._(ConfigurationItemAttributeType.optional);
|
||||
|
||||
/// Represents an exception thrown when reading data into a [Configuration] fails.
|
||||
///
|
||||
/// This exception provides detailed information about the configuration error,
|
||||
/// including the configuration object where the error occurred, the error message,
|
||||
/// and optionally, the key path to the problematic configuration item.
|
||||
///
|
||||
/// The class offers two constructors:
|
||||
/// 1. A general constructor for creating exceptions with custom messages.
|
||||
/// 2. A specialized constructor [ConfigurationException.missingKeys] for creating
|
||||
/// exceptions specifically related to missing required keys.
|
||||
///
|
||||
/// The [toString] method provides a formatted error message that includes the
|
||||
/// configuration type, the key path (if available), and the error message.
|
||||
///
|
||||
/// Usage:
|
||||
/// ```dart
|
||||
/// throw ConfigurationException(
|
||||
/// myConfig,
|
||||
/// "Invalid value",
|
||||
/// keyPath: ['server', 'port'],
|
||||
/// );
|
||||
/// ```
|
||||
///
|
||||
/// Or for missing keys:
|
||||
/// ```dart
|
||||
/// throw ConfigurationException.missingKeys(
|
||||
/// myConfig,
|
||||
/// ['apiKey', 'secret'],
|
||||
/// );
|
||||
/// ```
|
||||
/// Thrown when reading data into a [Configuration] fails.
|
||||
class ConfigurationException {
|
||||
/// Creates a new [ConfigurationException] instance.
|
||||
///
|
||||
/// This constructor is used to create an exception that provides information
|
||||
/// about a configuration error.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [configuration]: The [Configuration] object where the error occurred.
|
||||
/// - [message]: A string describing the error.
|
||||
/// - [keyPath]: An optional list of keys or indices that specify the path to
|
||||
/// the problematic configuration item. Defaults to an empty list.
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// throw ConfigurationException(
|
||||
/// myConfig,
|
||||
/// "Invalid port number",
|
||||
/// keyPath: ['server', 'port'],
|
||||
/// );
|
||||
/// ```
|
||||
ConfigurationException(
|
||||
this.configuration,
|
||||
this.message, {
|
||||
this.keyPath = const [],
|
||||
});
|
||||
|
||||
/// Creates a [ConfigurationException] for missing required keys.
|
||||
///
|
||||
/// This constructor is specifically used to create an exception when one or more
|
||||
/// required keys are missing from the configuration.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [configuration]: The [Configuration] object where the missing keys were detected.
|
||||
/// - [missingKeys]: A list of strings representing the names of the missing required keys.
|
||||
/// - [keyPath]: An optional list of keys or indices that specify the path to the
|
||||
/// configuration item where the missing keys were expected. Defaults to an empty list.
|
||||
///
|
||||
/// The [message] is automatically generated to list all the missing keys.
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// throw ConfigurationException.missingKeys(
|
||||
/// myConfig,
|
||||
/// ['apiKey', 'secret'],
|
||||
/// keyPath: ['server', 'authentication'],
|
||||
/// );
|
||||
/// ```
|
||||
ConfigurationException.missingKeys(
|
||||
this.configuration,
|
||||
List<String> missingKeys, {
|
||||
|
|
@ -478,52 +219,17 @@ class ConfigurationException {
|
|||
}) : message =
|
||||
"missing required key(s): ${missingKeys.map((s) => "'$s'").join(", ")}";
|
||||
|
||||
/// The [Configuration] instance in which this exception occurred.
|
||||
///
|
||||
/// This field stores a reference to the [Configuration] object that was being
|
||||
/// processed when the exception was thrown. It provides context about which
|
||||
/// specific configuration was involved in the error, allowing for more
|
||||
/// detailed error reporting and easier debugging.
|
||||
///
|
||||
/// The stored configuration can be used to access additional information
|
||||
/// about the configuration state at the time of the error, which can be
|
||||
/// helpful in diagnosing and resolving configuration-related issues.
|
||||
/// The [Configuration] in which this exception occurred.
|
||||
final Configuration configuration;
|
||||
|
||||
/// The reason for the exception.
|
||||
///
|
||||
/// This field contains a string describing the specific error or reason
|
||||
/// why the [ConfigurationException] was thrown. It provides detailed
|
||||
/// information about what went wrong during the configuration process.
|
||||
///
|
||||
/// The message can be used for logging, debugging, or displaying error
|
||||
/// information to users or developers to help diagnose and fix
|
||||
/// configuration-related issues.
|
||||
final String message;
|
||||
|
||||
/// The key path of the object being evaluated.
|
||||
/// The key of the object being evaluated.
|
||||
///
|
||||
/// Either a string (adds '.name') or an int (adds '\[value\]').
|
||||
final List<dynamic> keyPath;
|
||||
|
||||
/// Provides a string representation of the [ConfigurationException].
|
||||
///
|
||||
/// This method generates a formatted error message that includes:
|
||||
/// - The type of the configuration where the error occurred
|
||||
/// - The key path to the problematic configuration item (if available)
|
||||
/// - The specific error message
|
||||
///
|
||||
/// The key path is constructed by joining the elements in [keyPath]:
|
||||
/// - String elements are joined with dots (e.g., 'server.port')
|
||||
/// - Integer elements are enclosed in square brackets (e.g., '[0]')
|
||||
///
|
||||
/// If [keyPath] is empty, a general error message for the configuration is returned.
|
||||
///
|
||||
/// Returns:
|
||||
/// A string containing the formatted error message.
|
||||
///
|
||||
/// Throws:
|
||||
/// [StateError] if an element in [keyPath] is neither a String nor an int.
|
||||
@override
|
||||
String toString() {
|
||||
if (keyPath.isEmpty) {
|
||||
|
|
@ -548,78 +254,16 @@ class ConfigurationException {
|
|||
}
|
||||
}
|
||||
|
||||
/// Represents an error that occurs when a [Configuration] subclass is invalid and requires a change in code.
|
||||
///
|
||||
/// This exception is thrown when there's a structural or logical issue with a [Configuration] subclass
|
||||
/// that cannot be resolved at runtime and requires modifications to the code itself.
|
||||
///
|
||||
/// The [ConfigurationError] provides information about the specific [Configuration] type that caused the error
|
||||
/// and a descriptive message explaining the nature of the invalidity.
|
||||
///
|
||||
/// Properties:
|
||||
/// - [type]: The Type of the [Configuration] subclass where the error occurred.
|
||||
/// - [message]: A String describing the specific error or invalidity.
|
||||
///
|
||||
/// Usage:
|
||||
/// ```dart
|
||||
/// throw ConfigurationError(MyConfig, "Missing required property 'apiKey'");
|
||||
/// ```
|
||||
///
|
||||
/// The [toString] method provides a formatted error message combining the invalid type and the error description.
|
||||
/// Thrown when [Configuration] subclass is invalid and requires a change in code.
|
||||
class ConfigurationError {
|
||||
/// Creates a new [ConfigurationError] instance.
|
||||
///
|
||||
/// This constructor is used to create an error that indicates an invalid [Configuration] subclass
|
||||
/// which requires changes to the code itself to resolve.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [type]: The [Type] of the [Configuration] subclass where the error occurred.
|
||||
/// - [message]: A string describing the specific error or invalidity.
|
||||
///
|
||||
/// This error is typically thrown when there's a structural or logical issue with a [Configuration]
|
||||
/// subclass that cannot be resolved at runtime and requires modifications to the code.
|
||||
///
|
||||
/// Example:
|
||||
/// ```dart
|
||||
/// throw ConfigurationError(MyConfig, "Missing required property 'apiKey'");
|
||||
/// ```
|
||||
ConfigurationError(this.type, this.message);
|
||||
|
||||
/// The type of [Configuration] in which this error appears.
|
||||
///
|
||||
/// This property stores the [Type] of the [Configuration] subclass that is
|
||||
/// considered invalid or problematic. It provides context about which specific
|
||||
/// configuration class triggered the error, allowing for more precise error
|
||||
/// reporting and easier debugging.
|
||||
///
|
||||
/// The stored type can be used to identify the exact [Configuration] subclass
|
||||
/// that needs to be modified or corrected to resolve the error.
|
||||
/// The type of [Configuration] in which this error appears in.
|
||||
final Type type;
|
||||
|
||||
/// The reason for the error.
|
||||
///
|
||||
/// This field contains a string describing the specific error or reason
|
||||
/// why the [ConfigurationError] was thrown. It provides detailed
|
||||
/// information about what makes the [Configuration] subclass invalid
|
||||
/// or problematic.
|
||||
///
|
||||
/// The message can be used for logging, debugging, or displaying error
|
||||
/// information to developers to help diagnose and fix issues related
|
||||
/// to the structure or implementation of the [Configuration] subclass.
|
||||
String message;
|
||||
|
||||
/// Returns a string representation of the [ConfigurationError].
|
||||
///
|
||||
/// This method generates a formatted error message that includes:
|
||||
/// - The type of the invalid [Configuration] subclass
|
||||
/// - The specific error message describing the invalidity
|
||||
///
|
||||
/// The resulting string is useful for logging, debugging, or displaying
|
||||
/// error information to developers to help identify and fix issues with
|
||||
/// the [Configuration] subclass implementation.
|
||||
///
|
||||
/// Returns:
|
||||
/// A string containing the formatted error message.
|
||||
@override
|
||||
String toString() {
|
||||
return "Invalid configuration type '$type'. $message";
|
||||
|
|
|
|||
|
|
@ -10,73 +10,17 @@
|
|||
import 'package:protevus_config/config.dart';
|
||||
|
||||
/// A [Configuration] to represent a database connection configuration.
|
||||
///
|
||||
/// This class extends [Configuration] and provides properties and methods
|
||||
/// for managing database connection settings. It includes properties for
|
||||
/// host, port, database name, username, password, and a flag for temporary
|
||||
/// databases. The class supports initialization from various sources
|
||||
/// (file, string, map) and provides a custom decoder for parsing connection
|
||||
/// strings.
|
||||
///
|
||||
/// Properties:
|
||||
/// - [host]: The host of the database to connect to (required).
|
||||
/// - [port]: The port of the database to connect to (required).
|
||||
/// - [databaseName]: The name of the database to connect to (required).
|
||||
/// - [username]: A username for authenticating to the database (optional).
|
||||
/// - [password]: A password for authenticating to the database (optional).
|
||||
/// - [isTemporary]: A flag to represent permanence, used for test suites (optional).
|
||||
///
|
||||
/// The [decode] method allows parsing of connection strings or maps to
|
||||
/// populate the configuration properties.
|
||||
class DatabaseConfiguration extends Configuration {
|
||||
/// Default constructor for DatabaseConfiguration.
|
||||
///
|
||||
/// Creates a new instance of DatabaseConfiguration without initializing any properties.
|
||||
/// Properties can be set manually or through the decode method after instantiation.
|
||||
/// Default constructor.
|
||||
DatabaseConfiguration();
|
||||
|
||||
/// Creates a [DatabaseConfiguration] instance from a file.
|
||||
///
|
||||
/// This named constructor initializes the configuration by reading from a file.
|
||||
/// The file path is passed to the superclass constructor [Configuration.fromFile].
|
||||
///
|
||||
/// Parameters:
|
||||
/// [file]: The path to the configuration file.
|
||||
DatabaseConfiguration.fromFile(super.file) : super.fromFile();
|
||||
|
||||
/// Creates a [DatabaseConfiguration] instance from a YAML string.
|
||||
///
|
||||
/// This named constructor initializes the configuration by parsing a YAML string.
|
||||
/// The YAML string is passed to the superclass constructor [Configuration.fromString].
|
||||
///
|
||||
/// Parameters:
|
||||
/// [yaml]: A string containing YAML-formatted configuration data.
|
||||
DatabaseConfiguration.fromString(super.yaml) : super.fromString();
|
||||
|
||||
/// Creates a [DatabaseConfiguration] instance from a Map.
|
||||
///
|
||||
/// This named constructor initializes the configuration using a Map of key-value pairs.
|
||||
/// The Map is passed to the superclass constructor [Configuration.fromMap].
|
||||
///
|
||||
/// Parameters:
|
||||
/// [yaml]: A Map containing configuration data.
|
||||
DatabaseConfiguration.fromMap(super.yaml) : super.fromMap();
|
||||
|
||||
/// Creates a [DatabaseConfiguration] instance with all connection information provided.
|
||||
///
|
||||
/// This named constructor allows for the direct initialization of all database connection
|
||||
/// properties in a single call. It sets both required and optional properties.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [username]: The username for database authentication (optional).
|
||||
/// [password]: The password for database authentication (optional).
|
||||
/// [host]: The host address of the database server (required).
|
||||
/// [port]: The port number on which the database server is listening (required).
|
||||
/// [databaseName]: The name of the specific database to connect to (required).
|
||||
/// [isTemporary]: A flag indicating if this is a temporary database connection (optional, defaults to false).
|
||||
///
|
||||
/// This constructor provides a convenient way to create a fully configured
|
||||
/// [DatabaseConfiguration] object when all connection details are known in advance.
|
||||
/// A named constructor that contains all of the properties of this instance.
|
||||
DatabaseConfiguration.withConnectionInfo(
|
||||
this.username,
|
||||
this.password,
|
||||
|
|
@ -88,102 +32,36 @@ class DatabaseConfiguration extends Configuration {
|
|||
|
||||
/// The host of the database to connect to.
|
||||
///
|
||||
/// This property represents the hostname or IP address of the database server
|
||||
/// that this configuration will connect to. It is a required field and must be
|
||||
/// set before attempting to establish a database connection.
|
||||
///
|
||||
/// The value should be a valid hostname (e.g., 'localhost', 'db.example.com')
|
||||
/// or an IP address (e.g., '192.168.1.100').
|
||||
///
|
||||
/// This property is marked as 'late', which means it must be initialized
|
||||
/// before it's first used, but not necessarily in the constructor.
|
||||
/// This property is required.
|
||||
late String host;
|
||||
|
||||
/// The port of the database to connect to.
|
||||
///
|
||||
/// This property represents the network port number on which the database server
|
||||
/// is listening for connections. It is a required field and must be set before
|
||||
/// attempting to establish a database connection.
|
||||
///
|
||||
/// The value should be a valid port number, typically an integer between 0 and 65535.
|
||||
/// Common database port numbers include 5432 for PostgreSQL, 3306 for MySQL,
|
||||
/// and 1433 for SQL Server, but the actual port may vary depending on the specific
|
||||
/// database configuration.
|
||||
///
|
||||
/// This property is marked as 'late', which means it must be initialized
|
||||
/// before it's first used, but not necessarily in the constructor.
|
||||
/// This property is required.
|
||||
late int port;
|
||||
|
||||
/// The name of the database to connect to.
|
||||
///
|
||||
/// This property represents the specific database name within the database server
|
||||
/// that this configuration will target. It is a required field and must be set
|
||||
/// before attempting to establish a database connection.
|
||||
///
|
||||
/// The value should be a valid database name as defined in your database server.
|
||||
/// For example, it could be 'myapp_database', 'users_db', or 'production_data'.
|
||||
///
|
||||
/// This property is marked as 'late', which means it must be initialized
|
||||
/// before it's first used, but not necessarily in the constructor.
|
||||
/// This property is required.
|
||||
late String databaseName;
|
||||
|
||||
/// A username for authenticating to the database.
|
||||
///
|
||||
/// This property represents the username used for authentication when connecting
|
||||
/// to the database. It is an optional field, meaning it can be null if authentication
|
||||
/// is not required or if other authentication methods are used.
|
||||
///
|
||||
/// The value should be a string containing the username as configured in the
|
||||
/// database server for this particular connection. For example, it could be
|
||||
/// 'db_user', 'admin', or 'app_service_account'.
|
||||
///
|
||||
/// If this property is set, it is typically used in conjunction with the [password]
|
||||
/// property to form a complete set of credentials for database authentication.
|
||||
/// This property is optional.
|
||||
String? username;
|
||||
|
||||
/// A password for authenticating to the database.
|
||||
///
|
||||
/// This property represents the password used for authentication when connecting
|
||||
/// to the database. It is an optional field, meaning it can be null if authentication
|
||||
/// is not required or if other authentication methods are used.
|
||||
///
|
||||
/// The value should be a string containing the password that corresponds to the
|
||||
/// [username] for this database connection. For security reasons, it's important
|
||||
/// to handle this value carefully and avoid exposing it in logs or user interfaces.
|
||||
///
|
||||
/// If this property is set, it is typically used in conjunction with the [username]
|
||||
/// property to form a complete set of credentials for database authentication.
|
||||
///
|
||||
/// Note: In production environments, it's recommended to use secure methods of
|
||||
/// storing and retrieving passwords, such as environment variables or secure
|
||||
/// secret management systems, rather than hardcoding them in the configuration.
|
||||
/// This property is optional.
|
||||
String? password;
|
||||
|
||||
/// A flag to represent permanence of the database.
|
||||
/// A flag to represent permanence.
|
||||
///
|
||||
/// This flag is used for test suites that use a temporary database to run tests against,
|
||||
/// dropping it after the tests are complete.
|
||||
/// This property is optional.
|
||||
bool isTemporary = false;
|
||||
|
||||
/// Decodes and populates the configuration from a given value.
|
||||
///
|
||||
/// This method can handle two types of input:
|
||||
/// 1. A Map: In this case, it delegates to the superclass's decode method.
|
||||
/// 2. A String: It parses the string as a URI to extract database connection details.
|
||||
///
|
||||
/// For string input, it extracts:
|
||||
/// - Host and port from the URI
|
||||
/// - Database name from the path (if present)
|
||||
/// - Username and password from the userInfo part of the URI (if present)
|
||||
///
|
||||
/// After parsing, it calls the validate method to ensure all required fields are set.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [value]: The input to decode. Can be a Map or a String.
|
||||
///
|
||||
/// Throws:
|
||||
/// [ConfigurationException]: If the input is neither a Map nor a String.
|
||||
@override
|
||||
void decode(dynamic value) {
|
||||
if (value is Map) {
|
||||
|
|
@ -223,80 +101,27 @@ class DatabaseConfiguration extends Configuration {
|
|||
}
|
||||
|
||||
/// A [Configuration] to represent an external HTTP API.
|
||||
///
|
||||
/// This class extends [Configuration] and provides properties for managing
|
||||
/// external API connection settings. It includes properties for the base URL,
|
||||
/// client ID, and client secret.
|
||||
///
|
||||
/// The class supports initialization from various sources (file, string, map)
|
||||
/// through its constructors.
|
||||
///
|
||||
/// Properties:
|
||||
/// - [baseURL]: The base URL of the described API (required).
|
||||
/// - [clientID]: The client ID for API authentication (optional).
|
||||
/// - [clientSecret]: The client secret for API authentication (optional).
|
||||
///
|
||||
/// Constructors:
|
||||
/// - Default constructor: Creates an empty instance.
|
||||
/// - [fromFile]: Initializes from a configuration file.
|
||||
/// - [fromString]: Initializes from a YAML string.
|
||||
/// - [fromMap]: Initializes from a Map.
|
||||
class APIConfiguration extends Configuration {
|
||||
/// Default constructor for APIConfiguration.
|
||||
///
|
||||
/// Creates a new instance of APIConfiguration without initializing any properties.
|
||||
/// Properties can be set manually or through the decode method after instantiation.
|
||||
APIConfiguration();
|
||||
|
||||
/// Creates an [APIConfiguration] instance from a file.
|
||||
///
|
||||
/// This named constructor initializes the configuration by reading from a file.
|
||||
/// The file path is passed to the superclass constructor [Configuration.fromFile].
|
||||
///
|
||||
/// Parameters:
|
||||
/// [file]: The path to the configuration file.
|
||||
APIConfiguration.fromFile(super.file) : super.fromFile();
|
||||
|
||||
/// Creates an [APIConfiguration] instance from a YAML string.
|
||||
///
|
||||
/// This named constructor initializes the configuration by parsing a YAML string.
|
||||
/// The YAML string is passed to the superclass constructor [Configuration.fromString].
|
||||
///
|
||||
/// Parameters:
|
||||
/// [yaml]: A string containing YAML-formatted configuration data.
|
||||
APIConfiguration.fromString(super.yaml) : super.fromString();
|
||||
|
||||
/// Creates an [APIConfiguration] instance from a Map.
|
||||
///
|
||||
/// This named constructor initializes the configuration using a Map of key-value pairs.
|
||||
/// The Map is passed to the superclass constructor [Configuration.fromMap].
|
||||
///
|
||||
/// Parameters:
|
||||
/// [yaml]: A Map containing configuration data.
|
||||
APIConfiguration.fromMap(super.yaml) : super.fromMap();
|
||||
|
||||
/// The base URL of the described API.
|
||||
///
|
||||
/// This property represents the root URL for the external API that this configuration
|
||||
/// is describing. It is a required field and must be set before using the API configuration.
|
||||
///
|
||||
/// The value should be a complete URL, including the protocol (http or https),
|
||||
/// domain name, and optionally the port and base path. It serves as the foundation
|
||||
/// for constructing full URLs to specific API endpoints.
|
||||
///
|
||||
/// This property is marked as 'late', which means it must be initialized
|
||||
/// before it's first used, but not necessarily in the constructor.
|
||||
///
|
||||
/// This property is required.
|
||||
/// Example: https://external.api.com:80/resources
|
||||
late String baseURL;
|
||||
|
||||
/// The client ID for API authentication.
|
||||
/// The client ID.
|
||||
///
|
||||
/// This property is optional.
|
||||
String? clientID;
|
||||
|
||||
/// The client secret for API authentication.
|
||||
/// The client secret.
|
||||
///
|
||||
/// This property is optional.
|
||||
String? clientSecret;
|
||||
|
|
|
|||
|
|
@ -7,31 +7,10 @@
|
|||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
/// An exception class used for intermediate error handling.
|
||||
///
|
||||
/// This class encapsulates an underlying exception and a key path,
|
||||
/// allowing for more detailed error reporting in nested structures.
|
||||
///
|
||||
/// [underlying] is the original exception that was caught.
|
||||
/// [keyPath] is a list representing the path to the error in a nested structure.
|
||||
class IntermediateException implements Exception {
|
||||
/// Creates an [IntermediateException] with the given [underlying] exception and [keyPath].
|
||||
///
|
||||
/// [underlying] is the original exception that was caught.
|
||||
/// [keyPath] is a list representing the path to the error in a nested structure.
|
||||
IntermediateException(this.underlying, this.keyPath);
|
||||
|
||||
/// The original exception that was caught.
|
||||
///
|
||||
/// This field stores the underlying exception that triggered the creation
|
||||
/// of this [IntermediateException]. It can be of any type, hence the
|
||||
/// [dynamic] type annotation.
|
||||
final dynamic underlying;
|
||||
|
||||
/// A list representing the path to the error in a nested structure.
|
||||
///
|
||||
/// This field stores the key path as a list of dynamic elements. Each element
|
||||
/// in the list represents a key or index in the nested structure, helping to
|
||||
/// pinpoint the exact location of the error.
|
||||
final List<dynamic> keyPath;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -8,47 +8,10 @@
|
|||
*/
|
||||
|
||||
import 'dart:mirrors';
|
||||
|
||||
import 'package:protevus_config/config.dart';
|
||||
|
||||
/// A codec for decoding and encoding values based on their type using reflection.
|
||||
///
|
||||
/// This class uses the dart:mirrors library to introspect types and provide
|
||||
/// appropriate decoding and encoding logic for various data types including
|
||||
/// int, bool, Configuration subclasses, List, and Map.
|
||||
///
|
||||
/// The class supports:
|
||||
/// - Decoding values from various input formats to their corresponding Dart types.
|
||||
/// - Generating source code strings for decoding operations.
|
||||
/// - Validating Configuration subclasses to ensure they have a default constructor.
|
||||
///
|
||||
/// Usage:
|
||||
/// ```dart
|
||||
/// final codec = MirrorTypeCodec(reflectType(SomeType));
|
||||
/// final decodedValue = codec._decodeValue(inputValue);
|
||||
/// final sourceCode = codec.source;
|
||||
/// ```
|
||||
///
|
||||
/// Note: This class relies heavily on reflection, which may have performance
|
||||
/// implications and is not supported in all Dart runtime environments.
|
||||
class MirrorTypeCodec {
|
||||
/// Constructor for MirrorTypeCodec.
|
||||
///
|
||||
/// This constructor takes a [TypeMirror] as its parameter and initializes the codec.
|
||||
/// It performs a validation check for Configuration subclasses to ensure they have
|
||||
/// a default (unnamed) constructor with all optional parameters.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [type]: The TypeMirror representing the type for which this codec is being created.
|
||||
///
|
||||
/// Throws:
|
||||
/// [StateError]: If the type is a subclass of Configuration and doesn't have
|
||||
/// an unnamed constructor with all optional parameters.
|
||||
///
|
||||
/// The constructor specifically:
|
||||
/// 1. Checks if the type is a subclass of Configuration.
|
||||
/// 2. If so, it verifies the presence of a default constructor.
|
||||
/// 3. Throws a StateError if the required constructor is missing, providing
|
||||
/// a detailed error message to guide the developer.
|
||||
MirrorTypeCodec(this.type) {
|
||||
if (type.isSubtypeOf(reflectType(Configuration))) {
|
||||
final klass = type as ClassMirror;
|
||||
|
|
@ -69,34 +32,8 @@ class MirrorTypeCodec {
|
|||
}
|
||||
}
|
||||
|
||||
/// The [TypeMirror] representing the type for which this codec is created.
|
||||
///
|
||||
/// This field stores the reflection information about the type that this
|
||||
/// [MirrorTypeCodec] instance is designed to handle. It is used throughout
|
||||
/// the class to determine how to decode and encode values of this type.
|
||||
final TypeMirror type;
|
||||
|
||||
/// Decodes a value based on its type using reflection.
|
||||
///
|
||||
/// This method takes a [dynamic] input value and decodes it according to the
|
||||
/// type specified by this codec's [type] property. It supports decoding for:
|
||||
/// - Integers
|
||||
/// - Booleans
|
||||
/// - Configuration subclasses
|
||||
/// - Lists
|
||||
/// - Maps
|
||||
///
|
||||
/// If the input type doesn't match any of these, the original value is returned.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [value]: The input value to be decoded.
|
||||
///
|
||||
/// Returns:
|
||||
/// The decoded value, with its type corresponding to the codec's [type].
|
||||
///
|
||||
/// Throws:
|
||||
/// May throw exceptions if decoding fails, particularly for nested structures
|
||||
/// like Lists and Maps.
|
||||
dynamic _decodeValue(dynamic value) {
|
||||
if (type.isSubtypeOf(reflectType(int))) {
|
||||
return _decodeInt(value);
|
||||
|
|
@ -113,21 +50,6 @@ class MirrorTypeCodec {
|
|||
return value;
|
||||
}
|
||||
|
||||
/// Decodes a boolean value from various input types.
|
||||
///
|
||||
/// This method handles the conversion of input values to boolean:
|
||||
/// - If the input is a String, it returns true if the string is "true" (case-sensitive),
|
||||
/// and false otherwise.
|
||||
/// - For non-String inputs, it attempts to cast the value directly to a bool.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [value]: The input value to be decoded into a boolean.
|
||||
///
|
||||
/// Returns:
|
||||
/// A boolean representation of the input value.
|
||||
///
|
||||
/// Throws:
|
||||
/// TypeError: If the input cannot be cast to a bool (for non-String inputs).
|
||||
dynamic _decodeBool(dynamic value) {
|
||||
if (value is String) {
|
||||
return value == "true";
|
||||
|
|
@ -136,21 +58,6 @@ class MirrorTypeCodec {
|
|||
return value as bool;
|
||||
}
|
||||
|
||||
/// Decodes an integer value from various input types.
|
||||
///
|
||||
/// This method handles the conversion of input values to integers:
|
||||
/// - If the input is a String, it attempts to parse it as an integer.
|
||||
/// - For non-String inputs, it attempts to cast the value directly to an int.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [value]: The input value to be decoded into an integer.
|
||||
///
|
||||
/// Returns:
|
||||
/// An integer representation of the input value.
|
||||
///
|
||||
/// Throws:
|
||||
/// FormatException: If the input String cannot be parsed as an integer.
|
||||
/// TypeError: If the input cannot be cast to an int (for non-String inputs).
|
||||
dynamic _decodeInt(dynamic value) {
|
||||
if (value is String) {
|
||||
return int.parse(value);
|
||||
|
|
@ -159,21 +66,6 @@ class MirrorTypeCodec {
|
|||
return value as int;
|
||||
}
|
||||
|
||||
/// Decodes a Configuration object from the given input.
|
||||
///
|
||||
/// This method creates a new instance of the Configuration subclass
|
||||
/// represented by this codec's type, and then decodes the input object
|
||||
/// into it.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [object]: The input object to be decoded into a Configuration instance.
|
||||
///
|
||||
/// Returns:
|
||||
/// A new instance of the Configuration subclass, populated with the decoded data.
|
||||
///
|
||||
/// Throws:
|
||||
/// May throw exceptions if the instantiation fails or if the decode
|
||||
/// method of the Configuration subclass throws an exception.
|
||||
Configuration _decodeConfig(dynamic object) {
|
||||
final item = (type as ClassMirror).newInstance(Symbol.empty, []).reflectee
|
||||
as Configuration;
|
||||
|
|
@ -183,26 +75,6 @@ class MirrorTypeCodec {
|
|||
return item;
|
||||
}
|
||||
|
||||
/// Decodes a List value based on the codec's type parameters.
|
||||
///
|
||||
/// This method creates a new List instance and populates it with decoded elements
|
||||
/// from the input List. It uses an inner decoder to process each element according
|
||||
/// to the type specified in the codec's type arguments.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [value]: The input List to be decoded.
|
||||
///
|
||||
/// Returns:
|
||||
/// A new List containing the decoded elements.
|
||||
///
|
||||
/// Throws:
|
||||
/// IntermediateException: If an error occurs during the decoding of any element.
|
||||
/// The exception includes the index of the problematic element in its keyPath.
|
||||
///
|
||||
/// Note:
|
||||
/// - The method creates a growable List.
|
||||
/// - It uses reflection to create the new List instance.
|
||||
/// - Each element is decoded using an inner decoder based on the first type argument.
|
||||
List _decodeList(List value) {
|
||||
final out = (type as ClassMirror).newInstance(const Symbol('empty'), [], {
|
||||
const Symbol('growable'): true,
|
||||
|
|
@ -222,27 +94,6 @@ class MirrorTypeCodec {
|
|||
return out;
|
||||
}
|
||||
|
||||
/// Decodes a Map value based on the codec's type parameters.
|
||||
///
|
||||
/// This method creates a new Map instance and populates it with decoded key-value pairs
|
||||
/// from the input Map. It uses an inner decoder to process each value according
|
||||
/// to the type specified in the codec's type arguments.
|
||||
///
|
||||
/// Parameters:
|
||||
/// [value]: The input Map to be decoded.
|
||||
///
|
||||
/// Returns:
|
||||
/// A new Map containing the decoded key-value pairs.
|
||||
///
|
||||
/// Throws:
|
||||
/// StateError: If any key in the input Map is not a String.
|
||||
/// IntermediateException: If an error occurs during the decoding of any value.
|
||||
/// The exception includes the key of the problematic value in its keyPath.
|
||||
///
|
||||
/// Note:
|
||||
/// - The method creates a new Map instance using reflection.
|
||||
/// - It enforces that all keys must be Strings.
|
||||
/// - Each value is decoded using an inner decoder based on the last type argument.
|
||||
Map<dynamic, dynamic> _decodeMap(Map value) {
|
||||
final map =
|
||||
(type as ClassMirror).newInstance(Symbol.empty, []).reflectee as Map;
|
||||
|
|
@ -266,36 +117,10 @@ class MirrorTypeCodec {
|
|||
return map;
|
||||
}
|
||||
|
||||
/// Returns a string representation of the expected type for this codec.
|
||||
///
|
||||
/// This getter uses the [reflectedType] property of the [type] field
|
||||
/// to obtain a string representation of the type that this codec is
|
||||
/// expecting to handle. This is useful for generating type-specific
|
||||
/// decoding logic or for debugging purposes.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [String] representing the name of the expected type.
|
||||
String get expectedType {
|
||||
return type.reflectedType.toString();
|
||||
}
|
||||
|
||||
/// Returns the source code for decoding a value based on its type.
|
||||
///
|
||||
/// This getter generates and returns a string containing Dart code that can be used
|
||||
/// to decode a value of the type represented by this codec. The returned code varies
|
||||
/// depending on the type:
|
||||
///
|
||||
/// - For [int], it returns code to parse integers from strings or cast to int.
|
||||
/// - For [bool], it returns code to convert strings to booleans or cast to bool.
|
||||
/// - For [Configuration] subclasses, it returns code to create and decode a new instance.
|
||||
/// - For [List], it returns code to decode each element of the list.
|
||||
/// - For [Map], it returns code to decode each value in the map.
|
||||
/// - For any other type, it returns code that simply returns the input value unchanged.
|
||||
///
|
||||
/// The generated code assumes the input value is named 'v'.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [String] containing Dart code for decoding the value.
|
||||
String get source {
|
||||
if (type.isSubtypeOf(reflectType(int))) {
|
||||
return _decodeIntSource;
|
||||
|
|
@ -312,20 +137,6 @@ class MirrorTypeCodec {
|
|||
return "return v;";
|
||||
}
|
||||
|
||||
/// Generates source code for decoding a List value.
|
||||
///
|
||||
/// This getter creates a string containing Dart code that decodes a List
|
||||
/// based on the codec's type parameters. The generated code:
|
||||
/// - Creates a new List to store decoded elements.
|
||||
/// - Defines an inner decoder function for processing each element.
|
||||
/// - Iterates through the input List, decoding each element.
|
||||
/// - Handles exceptions, wrapping them in IntermediateException with the index.
|
||||
///
|
||||
/// The decoder function uses the source code from the inner codec,
|
||||
/// which is based on the first type argument of the List.
|
||||
///
|
||||
/// Returns:
|
||||
/// A String containing the Dart code for List decoding.
|
||||
String get _decodeListSource {
|
||||
final typeParam = MirrorTypeCodec(type.typeArguments.first);
|
||||
return """
|
||||
|
|
@ -348,21 +159,6 @@ return out;
|
|||
""";
|
||||
}
|
||||
|
||||
/// Generates source code for decoding a Map value.
|
||||
///
|
||||
/// This getter creates a string containing Dart code that decodes a Map
|
||||
/// based on the codec's type parameters. The generated code:
|
||||
/// - Creates a new Map to store decoded key-value pairs.
|
||||
/// - Defines an inner decoder function for processing each value.
|
||||
/// - Iterates through the input Map, ensuring all keys are Strings.
|
||||
/// - Decodes each value using the inner decoder function.
|
||||
/// - Handles exceptions, wrapping them in IntermediateException with the key.
|
||||
///
|
||||
/// The decoder function uses the source code from the inner codec,
|
||||
/// which is based on the last type argument of the Map.
|
||||
///
|
||||
/// Returns:
|
||||
/// A String containing the Dart code for Map decoding.
|
||||
String get _decodeMapSource {
|
||||
final typeParam = MirrorTypeCodec(type.typeArguments.last);
|
||||
return """
|
||||
|
|
@ -389,17 +185,6 @@ return map;
|
|||
""";
|
||||
}
|
||||
|
||||
/// Generates source code for decoding a Configuration object.
|
||||
///
|
||||
/// This getter returns a string containing Dart code that:
|
||||
/// 1. Creates a new instance of the Configuration subclass represented by [expectedType].
|
||||
/// 2. Calls the `decode` method on this new instance, passing in the input value 'v'.
|
||||
/// 3. Returns the decoded Configuration object.
|
||||
///
|
||||
/// The generated code assumes the input value is named 'v'.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [String] containing Dart code for decoding a Configuration object.
|
||||
String get _decodeConfigSource {
|
||||
return """
|
||||
final item = $expectedType();
|
||||
|
|
@ -410,17 +195,6 @@ return map;
|
|||
""";
|
||||
}
|
||||
|
||||
/// Generates source code for decoding an integer value.
|
||||
///
|
||||
/// This getter returns a string containing Dart code that:
|
||||
/// 1. Checks if the input value 'v' is a String.
|
||||
/// 2. If it is a String, parses it to an integer using `int.parse()`.
|
||||
/// 3. If it's not a String, casts the value directly to an int.
|
||||
///
|
||||
/// The generated code assumes the input value is named 'v'.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [String] containing Dart code for decoding an integer value.
|
||||
String get _decodeIntSource {
|
||||
return """
|
||||
if (v is String) {
|
||||
|
|
@ -431,17 +205,6 @@ return map;
|
|||
""";
|
||||
}
|
||||
|
||||
/// Generates source code for decoding a boolean value.
|
||||
///
|
||||
/// This getter returns a string containing Dart code that:
|
||||
/// 1. Checks if the input value 'v' is a String.
|
||||
/// 2. If it is a String, returns true if it equals "true", false otherwise.
|
||||
/// 3. If it's not a String, casts the value directly to a bool.
|
||||
///
|
||||
/// The generated code assumes the input value is named 'v'.
|
||||
///
|
||||
/// Returns:
|
||||
/// A [String] containing Dart code for decoding a boolean value.
|
||||
String get _decodeBoolSource {
|
||||
return """
|
||||
if (v is String) {
|
||||
|
|
@ -453,24 +216,6 @@ return map;
|
|||
}
|
||||
}
|
||||
|
||||
/// Represents a property of a Configuration class, providing metadata and decoding capabilities.
|
||||
///
|
||||
/// This class encapsulates information about a single property within a Configuration
|
||||
/// subclass, including its name, whether it's required, and how to decode its value.
|
||||
///
|
||||
/// It uses the [MirrorTypeCodec] to handle the decoding of values based on the property's type.
|
||||
///
|
||||
/// Key features:
|
||||
/// - Extracts the property name from the [VariableMirror].
|
||||
/// - Determines if the property is required based on its metadata.
|
||||
/// - Provides access to the decoding logic through the [codec] field.
|
||||
/// - Offers a method to decode input values, taking into account environment variables.
|
||||
///
|
||||
/// Usage:
|
||||
/// ```dart
|
||||
/// final property = MirrorConfigurationProperty(someVariableMirror);
|
||||
/// final decodedValue = property.decode(inputValue);
|
||||
/// ```
|
||||
class MirrorConfigurationProperty {
|
||||
MirrorConfigurationProperty(this.property)
|
||||
: codec = MirrorTypeCodec(property.type);
|
||||
|
|
|
|||
|
|
@ -8,73 +8,21 @@
|
|||
*/
|
||||
|
||||
import 'dart:mirrors';
|
||||
|
||||
import 'package:protevus_config/config.dart';
|
||||
import 'package:protevus_runtime/runtime.dart';
|
||||
|
||||
/// ConfigurationRuntimeImpl is a class that extends ConfigurationRuntime and implements SourceCompiler.
|
||||
///
|
||||
/// This class is responsible for handling the runtime configuration of the application. It uses
|
||||
/// Dart's mirror system to introspect and manipulate configuration objects at runtime.
|
||||
///
|
||||
/// Key features:
|
||||
/// - Decodes configuration input from a Map into a strongly-typed Configuration object
|
||||
/// - Validates the configuration to ensure all required fields are present
|
||||
/// - Generates implementation code for decoding and validating configurations
|
||||
/// - Collects and manages configuration properties
|
||||
///
|
||||
/// The class provides methods for decoding input, validating configurations, and compiling
|
||||
/// source code for runtime configuration handling. It also includes utility methods for
|
||||
/// collecting properties and generating implementation strings for decode and validate operations.
|
||||
class ConfigurationRuntimeImpl extends ConfigurationRuntime
|
||||
implements SourceCompiler {
|
||||
/// Constructs a ConfigurationRuntimeImpl instance for the given type.
|
||||
///
|
||||
/// The constructor initializes the type and properties of the configuration runtime.
|
||||
/// It collects properties using the `_collectProperties` method.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - type: The ClassMirror representing the type of the configuration object.
|
||||
ConfigurationRuntimeImpl(this.type) {
|
||||
// Should be done in the constructor so a type check could be run.
|
||||
properties = _collectProperties();
|
||||
}
|
||||
|
||||
/// The ClassMirror representing the type of the configuration object.
|
||||
///
|
||||
/// This field stores the reflection information for the configuration class,
|
||||
/// allowing for runtime introspection and manipulation of the configuration object.
|
||||
final ClassMirror type;
|
||||
|
||||
/// A map of property names to MirrorConfigurationProperty objects.
|
||||
///
|
||||
/// This late-initialized field stores the configuration properties of the class.
|
||||
/// Each key is a string representing the property name, and the corresponding value
|
||||
/// is a MirrorConfigurationProperty object containing metadata about that property.
|
||||
///
|
||||
/// The properties are collected during the initialization of the ConfigurationRuntimeImpl
|
||||
/// instance and are used for decoding, validating, and generating implementation code
|
||||
/// for the configuration.
|
||||
late final Map<String, MirrorConfigurationProperty> properties;
|
||||
|
||||
/// Decodes the input map into the given configuration object.
|
||||
///
|
||||
/// This method takes a [Configuration] object and a [Map] input, and populates
|
||||
/// the configuration object with the decoded values from the input map.
|
||||
///
|
||||
/// The method performs the following steps:
|
||||
/// 1. Creates a copy of the input map.
|
||||
/// 2. Iterates through each property in the configuration.
|
||||
/// 3. For each property, it attempts to decode the corresponding value from the input.
|
||||
/// 4. If the decoded value is not null and of the correct type, it sets the value on the configuration object.
|
||||
/// 5. After processing all properties, it checks if there are any unexpected keys left in the input map.
|
||||
///
|
||||
/// Throws a [ConfigurationException] if:
|
||||
/// - A decoded value is of the wrong type.
|
||||
/// - There are unexpected keys in the input map after processing all known properties.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - [configuration]: The Configuration object to be populated with decoded values.
|
||||
/// - [input]: A Map containing the input values to be decoded.
|
||||
@override
|
||||
void decode(Configuration configuration, Map input) {
|
||||
final values = Map.from(input);
|
||||
|
|
@ -113,24 +61,6 @@ class ConfigurationRuntimeImpl extends ConfigurationRuntime
|
|||
}
|
||||
}
|
||||
|
||||
/// Generates the implementation string for the decode method.
|
||||
///
|
||||
/// This getter creates a String representation of the decode method implementation.
|
||||
/// The generated code does the following:
|
||||
/// 1. Creates a copy of the input map.
|
||||
/// 2. Iterates through each property in the configuration.
|
||||
/// 3. For each property:
|
||||
/// - Retrieves the value from the input, considering environment variables.
|
||||
/// - If a value exists, it attempts to decode it.
|
||||
/// - Checks if the decoded value is of the expected type.
|
||||
/// - If valid, assigns the decoded value to the configuration object.
|
||||
/// 4. After processing all properties, it checks for any unexpected keys in the input.
|
||||
///
|
||||
/// The generated code includes proper error handling, throwing ConfigurationExceptions
|
||||
/// for type mismatches or unexpected input keys.
|
||||
///
|
||||
/// Returns:
|
||||
/// A String containing the implementation code for the decode method.
|
||||
String get decodeImpl {
|
||||
final buf = StringBuffer();
|
||||
|
||||
|
|
@ -168,22 +98,6 @@ class ConfigurationRuntimeImpl extends ConfigurationRuntime
|
|||
return buf.toString();
|
||||
}
|
||||
|
||||
/// Validates the given configuration object to ensure all required properties are present.
|
||||
///
|
||||
/// This method performs the following steps:
|
||||
/// 1. Creates a mirror of the configuration object for reflection.
|
||||
/// 2. Iterates through all properties of the configuration.
|
||||
/// 3. For each property, it checks if:
|
||||
/// - The property is required.
|
||||
/// - The property value is null or cannot be accessed.
|
||||
/// 4. Collects a list of all required properties that are missing or null.
|
||||
/// 5. If any required properties are missing, it throws a ConfigurationException.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - configuration: The Configuration object to be validated.
|
||||
///
|
||||
/// Throws:
|
||||
/// - ConfigurationException: If any required properties are missing or null.
|
||||
@override
|
||||
void validate(Configuration configuration) {
|
||||
final configMirror = reflect(configuration);
|
||||
|
|
@ -207,23 +121,6 @@ class ConfigurationRuntimeImpl extends ConfigurationRuntime
|
|||
}
|
||||
}
|
||||
|
||||
/// Collects and returns a map of configuration properties for the current type.
|
||||
///
|
||||
/// This method traverses the class hierarchy, starting from the current type
|
||||
/// up to (but not including) the Configuration class, collecting all non-static
|
||||
/// and non-private variable declarations. It then creates a map where:
|
||||
///
|
||||
/// - Keys are the string names of the properties
|
||||
/// - Values are MirrorConfigurationProperty objects created from the VariableMirrors
|
||||
///
|
||||
/// The method performs the following steps:
|
||||
/// 1. Initializes an empty list to store VariableMirror objects.
|
||||
/// 2. Traverses the class hierarchy, collecting relevant VariableMirrors.
|
||||
/// 3. Creates a map from the collected VariableMirrors.
|
||||
/// 4. Returns the resulting map of property names to MirrorConfigurationProperty objects.
|
||||
///
|
||||
/// Returns:
|
||||
/// A Map<String, MirrorConfigurationProperty> representing the configuration properties.
|
||||
Map<String, MirrorConfigurationProperty> _collectProperties() {
|
||||
final declarations = <VariableMirror>[];
|
||||
|
||||
|
|
@ -245,22 +142,6 @@ class ConfigurationRuntimeImpl extends ConfigurationRuntime
|
|||
return m;
|
||||
}
|
||||
|
||||
/// Generates the implementation string for the validate method.
|
||||
///
|
||||
/// This getter creates a String representation of the validate method implementation.
|
||||
/// The generated code does the following:
|
||||
/// 1. Initializes a list to store missing keys.
|
||||
/// 2. Iterates through each property in the configuration.
|
||||
/// 3. For each property:
|
||||
/// - Attempts to retrieve the property value from the configuration object.
|
||||
/// - Checks if the property is required and its value is null.
|
||||
/// - If required and null, or if an error occurs during retrieval, adds the property name to the missing keys list.
|
||||
/// 4. After checking all properties, throws a ConfigurationException if any keys are missing.
|
||||
///
|
||||
/// The generated code includes error handling to catch any issues during property access.
|
||||
///
|
||||
/// Returns:
|
||||
/// A String containing the implementation code for the validate method.
|
||||
String get validateImpl {
|
||||
final buf = StringBuffer();
|
||||
|
||||
|
|
@ -289,23 +170,6 @@ class ConfigurationRuntimeImpl extends ConfigurationRuntime
|
|||
return buf.toString();
|
||||
}
|
||||
|
||||
/// Compiles the configuration runtime implementation into a string representation.
|
||||
///
|
||||
/// This method generates the source code for a ConfigurationRuntimeImpl class
|
||||
/// that extends ConfigurationRuntime. The generated class includes implementations
|
||||
/// for the 'decode' and 'validate' methods.
|
||||
///
|
||||
/// The method performs the following steps:
|
||||
/// 1. Retrieves import directives for the current type and adds them to the generated code.
|
||||
/// 2. Adds an import for the intermediate_exception.dart file.
|
||||
/// 3. Creates an instance of ConfigurationRuntimeImpl.
|
||||
/// 4. Generates the class definition with implementations of decode and validate methods.
|
||||
///
|
||||
/// Parameters:
|
||||
/// - ctx: A BuildContext object used to retrieve import directives.
|
||||
///
|
||||
/// Returns:
|
||||
/// A Future<String> containing the generated source code for the ConfigurationRuntimeImpl class.
|
||||
@override
|
||||
Future<String> compile(BuildContext ctx) async {
|
||||
final directives = await ctx.getImportDirectives(
|
||||
|
|
|
|||
Loading…
Reference in a new issue