v0.1.1

Author: iyifr

.github/workflows/publish.yml

@@ -3,9 +3,9 @@ name: Publish to pub.dev
 on:
   push:
     branches:
-      - publish
+      - main
   pull_request:
-    branches: publish
+    branches: main
     tags:
       - 'v[0-9]+.[0-9]+.[0-9]+*'
 

README.md

@@ -5,24 +5,21 @@
 > A **lightweight**, **minimal**, and **incredibly fast** HTTP framework for productive and fun API
 > development with dart.
 
-**This is a very new project under active development**
+**This is a new project under active development**
 
 **Do not use in production as it could break unexpectedly.**
 
-You're welcome to try it out, see what breaks and give feedback. 
+There's an express-like server framework called `Alfred` in the dart ecosystem.
 
-There's already an express.js implementation called `Alfred` in the dart ecosystem. 
-
-This is the [H3](https://h3.unjs.io) implementation with similar design goals. 
-Special thanks to [Pooya Parsa](https://github.com/pi0) and the [Unjs](https://github.com/unjs) community for making a great library.
+This is the [H3](https://h3.unjs.io) implementation with similar design goals. Special thanks to
+[Pooya Parsa](https://github.com/pi0) and the [Unjs](https://github.com/unjs) community for making a
+awesome http library.
 
 ## Features
 
 - **Lightweight**: H4 ships with a small core and a set of composable utilities.
-- **Fast**: H4's trie-based router is incredibly fast, with support for route params and wildcard
-  patterns.
 - **Middleware**: H4 comes with built-in `onRequest` and `onError` middleware.
-- **Generic Handlers**: Specify the return type of your handler functions for increased type safety.
+- **Generic Handlers**: Specify the return type of your handler functions.
 
 ## Getting Started
 
@@ -59,13 +56,16 @@ void main() {
 ### Manual Start
 
 ```dart
-var app = createApp(port: 4000, autoStart: false);
+void main() {
+  var app = createApp(port: 4000, autoStart: false);
+  var router = createRouter();
 
-app.start().then((h4) => print(h4?.port));
+  app.use(router);
 
-var router = createRouter();
+  router.get("/hi", (event) => "Hi")
 
-app.use(router);
+  app.start()
+}
 ```
 
 ### Generic handlers
@@ -103,7 +103,7 @@ router.get('/error', (event) {
   // Code that could fail.
  }
  catch(e) {
-   throw CreateError(message: 'Error - $e', errorCode: 400);
+   throw CreateError(message: 'Womp Womp', errorCode: 400);
  }
 });
 ```
@@ -148,15 +148,30 @@ router.get('/articles/**', (event) {
 
 ## Utilities
 
-This is a design philosophy from [h3](https://h3.unjs.io).
+A set of composable utilities that help you add functionality to your server
 
-I'm working on adding an exhaustive list of composable utilities for easily extending functionality of your server.
+### `readRequestBody`
 
-More utilities will be added with each release and soon a guide to creating your own utils will be published.
+Reads the request body as `json` or `text` depending on the `contentType` of the request body.
 
-### `readRequestBody`
+```dart
+router.post("/vamos", (event) async {
+ var body = await readRequestBody(event);
+ return body;
+});
+```
 
-Reads the request body as `json` or `text` depending on the content type of the request body.
+### `getHeader`
+
+Get the value of any of the incoming request headers. For convenience you can use the HTTPHeaders
+utility to get header strings.
+
+```dart
+router.post("/vamos", (event) async {
+ var header = getHeader(event, HttpHeaders.userAgentHeader);
+ return body;
+});
+```
 
 ```dart
 router.post("/vamos", (event) async {
@@ -166,19 +181,23 @@ router.post("/vamos", (event) async {
 ```
 
 ## Contributing
+Contributors needed!
 
-We are looking for contributors!
-
-There's still quite a bit of work to do to get H4 to 1.0.0 and ready for production use.
+There's quite a bit of work to do to get H4 to 1.0.0 and ready for production use.
 
 If you find a bug or have an idea for a new feature, please
 [open an issue](https://github.com/iyifr/h4/issues/new) or submit a pull request.
 
 ### First Contribution
-
 A good first PR would be helping me improve the test coverage of this library. Or adding one of the
 utilities listed [here](https://h3.unjs.io/utils).
 
+### Running tests
+In the root directory run
+```bash
+dart test
+```
+
 ## Code of Conduct.
 
 Show respect and consideration for others when creating issues and contributing to the library. Only

bin/run.dart

@@ -3,19 +3,13 @@
 import 'dart:io';
 
 import 'package:h4/create.dart';
-import 'package:h4/src/create_error.dart';
-import 'package:h4/src/logger.dart';
 import 'package:h4/utils/get_header.dart';
 import 'package:h4/utils/get_query.dart';
 import 'package:h4/utils/read_request_body.dart';
 import 'package:h4/utils/set_response_header.dart';
 
 void main(List<String> arguments) async {
-  initLogger();
-
-  var app = createApp(port: 4000, autoStart: false);
-
-  await app.start().then((h4) => logger.warning(h4?.port));
+  var app = createApp(port: 5173);
 
   var router = createRouter();
 
@@ -32,7 +26,7 @@ void main(List<String> arguments) async {
 
   router.post("/vamos", (event) async {
     var body = await readRequestBody(event);
-    var header = getHeader(event, HttpHeaders.viaHeader);
+    var header = getHeader(event, HttpHeaders.userAgentHeader);
     var query = getQueryParams(event);
     setResponseHeader(event, HttpHeaders.contentTypeHeader,
         value: 'application/json');
@@ -46,6 +40,6 @@ void main(List<String> arguments) async {
   });
 
   router.get("/vamos", (event) {
-    throw CreateError(message: 'A grave error happened', errorCode: 404);
+    throw CreateError(message: 'A grave error happened');
   });
 }

lib/create.dart

@@ -1,3 +1,4 @@
+export 'package:h4/src/create_error.dart';
 import 'package:h4/src/h4.dart';
 import 'package:h4/src/router.dart';
 
@@ -24,7 +25,7 @@ import 'package:h4/src/router.dart';
 /// final app = createApp(autoStart: false)
 /// await app.start().then((h4) => print('App started on ${h4.port}'))
 /// ```
-H4 createApp({int? port, bool autoStart = true}) {
+H4 createApp({int port = 3000, bool autoStart = true}) {
   return H4(port: port, autoStart: autoStart);
 }
 

lib/src/create_error.dart

@@ -1,19 +1,21 @@
 import 'dart:io';
 
+/// Custom HTTP exception class for creating and throwing errors.
 class CreateError implements HttpException {
+  /// Message to send to the client.
   @override
-
-  /// Message to send to client.
   final String message;
 
   /// HTTP status code (defaults to 400).
   final int errorCode;
 
-  ///  * Creates a new `Error` that can be used to handle both internal and runtime errors.
+  /// Constructs a `CreateError` instance.
   ///
-  ///  * Pass an error message
+  /// Throws a custom error with the provided message and optional HTTP status code.
   ///
-  /// * Pass a http status code (defaults to 400) (optional)
+  /// Parameters:
+  /// - `message`: The error message to be sent to the client.
+  /// - `errorCode`: The HTTP status code for the error (defaults to 400 if not provided).
   CreateError({
     required this.message,
     this.errorCode = 400,

lib/src/h4.dart

@@ -2,6 +2,7 @@ import 'dart:io';
 import 'package:h4/src/create_error.dart';
 import 'package:h4/src/error_middleware.dart';
 import 'package:h4/src/logger.dart';
+import 'package:h4/src/port_taken.dart';
 import 'package:h4/src/router.dart';
 
 import '/src/index.dart';
@@ -22,7 +23,7 @@ class H4 {
       (e, s, event) => logger.severe(
           'Stack Trace \n $e \n $s \n Error occured at path -${event?.path}');
 
-  int? port;
+  int port;
 
   /// Constructs an instance of the `H4` class, which is the main entry point for
   /// your application.
@@ -45,22 +46,36 @@ class H4 {
   /// // Start the application on the default port (3000)
   /// final app = H4();
   /// ```
-  H4({this.port, bool autoStart = true}) {
-    autoStart ? start() : null;
+  H4({this.port = 3000, bool autoStart = true}) {
+    initLogger();
+
+    if (autoStart) {
+      start();
+    }
   }
 
   /// Initializes the server on **localhost** and starts listening for requests.
   Future<H4?> start() async {
     try {
+      var portReady = await isPortAvailable(port: port);
+
+      if (portReady == false) {
+        logger.info(
+            'Port $port is already taken, starting server on ${port + 1}');
+        port = port + 1;
+
+        start();
+      }
       server = await initializeHttpConnection(
-        port: port ?? 3000,
+        port: port,
       );
+      logger.info('Server started on port $port');
       _bootstrap();
+      return this;
     } catch (e) {
       logger.severe(e.toString());
       return null;
     }
-    return this;
   }
 
   /// Shuts down the server and stops listening to requests.
@@ -130,19 +145,9 @@ class H4 {
   }
 
   _bootstrap() {
-    // var newStream = server?.asBroadcastStream();
-
-    // newStream?.listen((HttpRequest req) {
-    //   var event = H4Event(req);
-    //   var params = router?.getParams(req.uri.path);
-    //   event.eventParams = params ?? {};
-    //   _onRequestHandler!(event);
-    // });
-
     server?.listen((HttpRequest request) {
       if (router == null) {
-        print(
-            "No router is defined, it is recommended to use createRouter() to define a router.");
+        logger.warning("No router is defined!");
       }
 
       // Find handler for that request
@@ -190,7 +195,7 @@ class H4 {
             statusCode: e.errorCode)(request);
       }
 
-      /// Catch non-explicity error when they occur and send a JSON payload to the client.
+      // Catch non-explicity error when they occur and send a JSON payload to the client.
       catch (e, trace) {
         defineErrorHandler(_errorHandler,
             params: params,

lib/src/logger.dart

@@ -5,6 +5,6 @@ var logger = Logger('H4');
 initLogger() {
   Logger.root.level = Level.ALL; // defaults to Level.INFO
   Logger.root.onRecord.listen((record) {
-    print('${record.level.name}: ${record.time}: ${record.message}');
+    print('${record.level.name}: ${record.message}');
   });
 }

lib/src/port_taken.dart

@@ -0,0 +1,13 @@
+import 'dart:io';
+
+Future<bool> isPortAvailable({required int port}) async {
+  try {
+    ServerSocket socket = await ServerSocket.bind('localhost', port);
+    await socket.close();
+    return true;
+  } on SocketException {
+    return false;
+  } catch (e) {
+    return false;
+  }
+}

lib/utils/get_header.dart

@@ -2,18 +2,56 @@ import 'dart:io';
 
 import 'package:h4/src/event.dart';
 
+/// ### Retrieves the value of a specific header from an event instance.
+///
+/// The `getHeader` function is used to extract the value of a specified header from an `H4Event` object. The `H4Event` object is expected to have a `node` property that contains an HTTP request, and the `node["value"]` property is assumed to represent the incoming HTTP request.
+///
+/// Parameters:
+/// - `event`: An `H4Event` instance.
+/// - `header`: The name of the header to retrieve.
+///
+/// Returns:
+/// The value of the specified header, or `null` if the header is not found.
 String? getHeader(H4Event event, String header) {
   return event.node["value"]?.headers.value(header);
 }
 
+/// Retrieves the headers of the incoming HTTP request from an `H4Event` instance.
+///
+/// The `getRequestHeaders` function is used to extract the headers of the incoming HTTP request from an `H4Event` object. The `H4Event` object is expected to have a `node` property that contains the HTTP request, and the `node["value"]` property is assumed to represent the incoming HTTP request.
+///
+/// Parameters:
+/// - `event`: An `H4Event` instance containing the HTTP request.
+///
+/// Returns:
+/// The headers of the incoming HTTP request.
 HttpHeaders? getRequestHeaders(H4Event event) {
   return event.node["value"]?.headers;
 }
 
+/// Retrieves the headers of the HTTP response from an `H4Event` instance.
+///
+/// The `getResponseHeaders` function is used to extract the headers of the HTTP response from an `H4Event` object. The `H4Event` object is expected to have a `node` property that contains the HTTP request, and the `node["value"]` property is assumed to represent the incoming HTTP request.
+///
+/// Parameters:
+/// - `event`: An `H4Event` instance containing the HTTP request.
+///
+/// Returns:
+/// The headers of the HTTP response, or `null` if the response is `null`.
 HttpHeaders? getResponseHeaders(H4Event event) {
   return event.node["value"]?.response.headers;
 }
 
+/// Retrieves the value of a specific header in the HTTP response from an `H4Event` instance.
+///
+/// The `getResponseHeader` function is used to extract the value of a specified header from the HTTP response of an `H4Event` object. The `H4Event` object is expected to have a `node` property that contains the HTTP request, and the `node["value"]` property is assumed to represent the incoming HTTP request.
+///
+/// Parameters:
+/// - `event`: An `H4Event` instance containing the HTTP request.
+/// - `header`: The name of the header to retrieve.
+///
+/// Returns:
+/// The value of the specified header, or `null` if the header is not found or the response is `null`.
 String? getResponseHeader(H4Event event, String header) {
   return event.node["value"]?.response.headers.value(header);
 }

lib/utils/read_request_body.dart

@@ -6,8 +6,8 @@ import 'package:either_dart/either.dart';
 import 'package:h4/src/event.dart';
 import 'package:h4/src/logger.dart';
 
-
-/// Read the body of the request.
+/// Read the body of the incoming event request.
+/// Returns the request body either as parsed json or a string.
 Future<dynamic> readRequestBody(H4Event event) async {
   var request = event.node["value"];