feat: Added shelf_routing and shelf_routing_generator packages

Author: BreX900

shelf_packages/shelf_routing/.gitignore

@@ -0,0 +1,22 @@
+# IntelliJ related
+.idea/
+*.iml
+*.ipr
+*.iws
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+
+# Files and directories created by pub.
+.dart_tool/
+.packages
+
+# Conventional directory for build outputs.
+build/
+
+# Avoid committing pubspec.lock for library packages; see
+# https://dart.dev/guides/libraries/private-files#pubspeclock.
+pubspec.lock

shelf_packages/shelf_routing/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+- Initial version.

shelf_packages/shelf_routing/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 BreX900
+
+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.

shelf_packages/shelf_routing/README.md

@@ -0,0 +1 @@
+../shelf_routing_generator/README.md

shelf_packages/shelf_routing/analysis_options.yaml

@@ -0,0 +1,30 @@
+# 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:mek_lints/dart_package.yaml
+
+# Uncomment the following section to specify additional rules.
+
+# linter:
+#   rules:
+#     - camel_case_types
+
+analyzer:
+  exclude:
+    - example/**
+
+# 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

shelf_packages/shelf_routing/example/main.dart

@@ -0,0 +1,3 @@
+/// See example in 'shelf_routing_generator' package.
+/// https://pub.dev/packages/shelf_routing_generator/example
+void main() {}

shelf_packages/shelf_routing/lib/shelf_routing.dart

@@ -0,0 +1,150 @@
+library shelf_routing;
+
+import 'package:meta/meta_meta.dart';
+
+export 'package:shelf_routing/src/get_request_extension.dart';
+export 'package:shelf_routing/src/json_response.dart';
+export 'package:shelf_routing/src/utils.dart';
+
+/// Annotation for top level getters to generate a router that handles all routers of the types
+/// passed using the package `shelf_routing_generator`.
+///
+/// **Example**
+/// ```dart
+/// // Always import 'shelf_router' without 'show' or 'as'.
+/// import 'package:shelf_router/shelf_router.dart';
+/// // Always import 'shelf_routing' without 'show' or 'as'.
+/// import 'package:shelf_routing/shelf_routing.dart' show Request, Response;
+///
+/// // Include generated code, this assumes current file is 'services_router.dart'.
+/// part 'services_router.g.dart';
+///
+/// // Get a router for all these services.
+/// @GenerateRouterFor([MyService, MyAnotherService])
+/// Router get router => _$router;
+/// ```
+@Target({TargetKind.getter})
+class GenerateRouterFor {
+  /// List of services that have a static getter that returns a Router
+  final List<Type> routables;
+
+  /// See class documentation
+  const GenerateRouterFor(this.routables);
+}
+
+/// Annotation for services using on methods the Route annotation to add a [prefix] when the router
+/// is mounted via the [GenerateRouterFor] annotation using the package `shelf_routing_generator`.
+///
+/// **Example**
+/// ```dart
+/// // Always import 'shelf_router' without 'show' or 'as'.
+/// import 'package:shelf_router/shelf_router.dart';
+/// // Always import 'shelf_routing' without 'show' or 'as'.
+/// import 'package:shelf_routing/shelf_routing.dart' show Request, Response;
+///
+/// // Include generated code, this assumes current file is 'service.dart'.
+/// part 'service.g.dart';
+///
+/// // Get a router for all these services.
+/// @Routable(prefix: '/say-hello')
+/// class Service {
+///   @Route.get('/<name>')
+///   Future<Response> _sayHello(Request request, String name) async {
+///     return Response.ok('hello $name');
+///   }
+///
+///   /// Get a router for this service.
+///   Router get router => _$ServiceRouter(this);
+/// }
+/// ```
+@Target({TargetKind.classType})
+class Routable {
+  /// Router prefix
+  final String prefix;
+
+  /// See class documentation
+  const Routable({required this.prefix});
+}
+
+/// Annotation for methods using Route annotation to indicate that the route should be called with
+/// this the header [name] using the package `shelf_routing_generator`.
+///
+/// **Example**
+/// ```dart
+/// import 'package:shelf/shelf.dart';
+/// // Always import 'shelf_routing' without 'show' or 'as'.
+/// import 'package:shelf_routing/shelf_routing.dart' show Request, Response;
+///
+/// // Include generated code, this assumes current file is 'service.dart'.
+/// part 'service.g.dart';
+///
+/// class Service {
+///   @Route.get('/<name>')
+///   @RouteHeader(name: 'authentication')
+///   Future<Response> _sayHello(Request request, String name) async {
+///     return Response.ok('hello $name');
+///   }
+/// }
+/// ```
+@Target({TargetKind.method})
+class RouteHeader {
+  /// The header name
+  final String name;
+
+  /// See class documentation
+  const RouteHeader({required this.name});
+}
+
+/// Identifies the data type of the request.
+enum BadRequestPosition {
+  /// Request header
+  header,
+
+  /// Path parameter
+  path,
+
+  /// Query parameter
+  queryParameter,
+
+  /// Request body
+  body
+}
+
+/// The exception that will be thrown in case the validation/parsing of the request fails.
+class BadRequestException implements Exception {
+  /// Identifies the type of invalid data.
+  final BadRequestPosition position;
+
+  /// The error generated by validation/parsing.
+  final Object error;
+
+  /// The stack trace generated by validation/parsing.
+  final StackTrace stackTrace;
+
+  /// The invalid field name.
+  final String? name;
+
+  /// Constructor for a request header error.
+  BadRequestException.header(
+    this.error,
+    this.stackTrace,
+    String this.name,
+  ) : position = BadRequestPosition.header;
+
+  /// Constructor for a request path parameter error.
+  BadRequestException.path(this.error, this.stackTrace)
+      : position = BadRequestPosition.path,
+        name = null;
+
+  /// Constructor for a request query parameter error.
+  BadRequestException.queryParameter(this.error, this.stackTrace, String this.name)
+      : position = BadRequestPosition.queryParameter;
+
+  /// Constructor for a request body error.
+  BadRequestException.body(this.error, this.stackTrace)
+      : position = BadRequestPosition.body,
+        name = null;
+
+  @override
+  String toString() => 'Missing or invalid ${position.name}${name != null ? ' "$name"' : ''}.';
+}

shelf_packages/shelf_routing/lib/src/formats.dart

@@ -0,0 +1,34 @@
+/// Specifies the array format (a single parameter with multiple parameter
+/// or multiple parameters with the same name).
+/// and the separator for array items.
+enum QueryParameterFormat {
+  /// Comma-separated values.
+  /// e.g. (foo,bar,baz)
+  // csv,
+  form,
+
+  /// Space-separated values.
+  /// e.g. (foo bar baz)
+  // ssv,
+  spaceDelimited,
+
+  /// Pipe-separated values.
+  /// e.g. (foo|bar|baz)
+  // pipes,
+  pipeDelimited,
+
+  /// Multiple parameter instances rather than multiple values.
+  /// e.g. (foo=value&foo=another_value)
+  // multi,
+  formExpanded;
+}
+
+/// Specifies the array format (a single parameter with multiple parameter
+/// or multiple parameters with the same name).
+/// and the separator for array items.
+enum HeaderFormat {
+  /// Comma-separated values.
+  /// e.g. (foo,bar,baz)
+  // csv,
+  simple,
+}

shelf_packages/shelf_routing/lib/src/get_request_extension.dart

@@ -0,0 +1,38 @@
+import 'package:shelf/shelf.dart';
+
+/// Getter definition for dependency injection.
+typedef RequestGetter = T Function<T extends Object>(Request request);
+
+/// Dependency injection extensions.
+extension GetterRequestExtensions on Request {
+  static const String _key = '_getter';
+
+  /// Retrieve data using the getter injected into the request via the [GetterMiddleware] middleware.
+  T get<T extends Object>() {
+    final getter = context[_key] as RequestGetter?;
+
+    assert(getter != null,
+        'Missing getter scope in request context.\nUse getterScope method to provider it.');
+
+    return getter!<T>(this);
+  }
+
+  /// Change the dependency injection [getter].
+  Request changeGetter(RequestGetter getter) => change(context: {_key: getter});
+}
+
+/// [Middleware] to inject [_getter] to retrieve data by dependency injection.
+class GetterMiddleware {
+  final RequestGetter _getter;
+
+  /// See class documentation
+  const GetterMiddleware(this._getter);
+
+  /// [Middleware] method
+  Handler call(Handler innerHandler) {
+    return (request) {
+      // ignore: discarded_futures
+      return innerHandler(request.changeGetter(_getter));
+    };
+  }
+}