From 57d8b4bed14b0b35d1d9753847ac39710e0d9be5 Mon Sep 17 00:00:00 2001 From: SrGooglo Date: Mon, 14 Apr 2025 15:54:05 +0000 Subject: [PATCH] documentation --- docs/server/available-engines.md | 11 ++-- docs/server/classes/endpoint.md | 35 ++++++++++++ docs/server/classes/route.md | 39 ++++++++++++++ docs/server/create-http-server-example.md | 23 +++++--- docs/server/define-routes.md | 0 docs/server/file-routes.md | 66 +++++++++++++++++++++++ server/src/classes/Endpoint/index.js | 3 ++ 7 files changed, 162 insertions(+), 15 deletions(-) create mode 100644 docs/server/classes/endpoint.md create mode 100644 docs/server/classes/route.md create mode 100644 docs/server/define-routes.md create mode 100644 docs/server/file-routes.md diff --git a/docs/server/available-engines.md b/docs/server/available-engines.md index f8bc0be..dfdc27e 100755 --- a/docs/server/available-engines.md +++ b/docs/server/available-engines.md @@ -1,11 +1,8 @@ # Available Engines -- `hyper-express` (default) - - Complete HTTP Server stack, including HTTP/2, SocketIO and Redis. - - Uses [HyperExpress](https://github.com/kartikk221/hyper-express) framework - -- `hyper-express-ng` - - Uses [HyperExpress](https://github.com/kartikk221/hyper-express) as base, implements experimental features & stacks. +- `he` (default) + - Complete HTTP Server stack, including HTTP/2 and RTEngine(websockets). + - Uses [HyperExpress](https://github.com/kartikk221/hyper-express) framework as a base. - `worker` - - Enables a worker thread to handle requests on ICP + - Enables a worker thread to handle requests on ICP. diff --git a/docs/server/classes/endpoint.md b/docs/server/classes/endpoint.md new file mode 100644 index 0000000..b01d3ce --- /dev/null +++ b/docs/server/classes/endpoint.md @@ -0,0 +1,35 @@ +## Endpoint Class + +`Endpoint` is a foundational class for handling HTTP requests within the Linebridge server framework. + +### Properties + +- `static _constructed`: Boolean flag indicating if an instance has been constructed. +- `static _class`: Boolean flag identifying the object as a class. +- `static useContexts`: Array that can define which contexts should be used. +- `static useMiddlewares`: Array that can define middlewares for the endpoint. +- `context`: Object containing context data passed to the handler. +- `handler`: Instance of HttpRequestHandler that processes the HTTP request. + +### Methods + +- `constructor(method, context)`: Creates a new Endpoint instance. + - `method`: Function to execute when the endpoint is triggered. + - `context`: Context data to be available during execution. +- `run`: The method that will be executed when handling a request. Can be defined in the constructor or in child classes. + +### Usage + +```js +// Direct usage with function +const getUsers = new Endpoint((req, res) => { + // Handle request and send response +}, contextObject) + +// Extended class usage +class GetUsers extends Endpoint { + run(req, res) { + // Handle request and send response + } +} +``` diff --git a/docs/server/classes/route.md b/docs/server/classes/route.md new file mode 100644 index 0000000..2bdbb01 --- /dev/null +++ b/docs/server/classes/route.md @@ -0,0 +1,39 @@ +## Route Class + +`Route` acts as a container for multiple HTTP method handlers related to the same route path. + +### Properties + +- `server`: Reference to the server instance. +- `params`: Configuration object containing: + - `route`: The URL path this route responds to. + - `useContexts`: Array of context keys to include. + - `useMiddlewares`: Array of middleware keys to apply. + - `handlers`: Object containing method handlers. +- `ctx`: Object storing context values that will be shared with Endpoints. + +### Methods + +- `constructor(server, params = {})`: Creates a new Route instance. + - [required] `server`: The server instance to register with. + - `params`: Configuration options for the route. +- `register()`: Registers all HTTP method handlers with the server. + +### Usage + +```js +class UserRoute extends Route { + static route = "/users" + static useContexts = ["database", "auth"] + static useMiddlewares = ["auth"] + + // Can be a Endpoint class or a Endpoint object + get = new GetUsers() + post = new CreateUser() + // Other methods... +} + +// Register with server +const userRoute = new UserRoute(server) +userRoute.register() +``` diff --git a/docs/server/create-http-server-example.md b/docs/server/create-http-server-example.md index 6d00cb8..f475746 100755 --- a/docs/server/create-http-server-example.md +++ b/docs/server/create-http-server-example.md @@ -1,18 +1,21 @@ ### Example -Create a http server +Create a basic http server, using linebridge bootloader. + ```js // index.js import { Server } from "linebridge" class MyAPI extends Server { - // set a id for the server + // set a id for the server (by default, it will fetch from package.json name) static refName = "my-api" - // define a file based router + + // define a file based router (by default, it will look for routes in the "/routes" folder) static routesPath = `${__dirname}/routes` - // define custom listen port + + // define custom listen port (by default, it will listen on port 3000) static listenPort = 3000 - // set manual routes + // define manual routes routes = { // basic route "/hi": { @@ -26,7 +29,7 @@ class MyAPI extends Server { // use custom middleware "/middleware-custom": { method: "get", - middlewares: [ + useMiddlewares: [ "custom-middleware" ], fn: async (req, res) => { @@ -91,14 +94,18 @@ class MyAPI extends Server { console.log("Server initialized") } - async onClose() { + // called when the server is closed + // MUST be synchronous, otherwise, may not work as expected. Thats a NodeJS limitation. + onClose() { console.log("Server closed") } } +// Call the built-in bootloader Boot(MyAPI) + ``` -Run the server +Run the server (using linebridge bootloader) ```bash linebridge-boot index.js ``` diff --git a/docs/server/define-routes.md b/docs/server/define-routes.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/server/file-routes.md b/docs/server/file-routes.md new file mode 100644 index 0000000..36f2f90 --- /dev/null +++ b/docs/server/file-routes.md @@ -0,0 +1,66 @@ +## File-based Routing +Linebridge has a built-in file-based routing system that will automatically register these routes based on the file structure. +By default, will search on `/routes` directory on cwd. + + +Create a directory structure that mirrors your route structure: + +``` +routes/ +├── users/ +│ ├── get.js # Handles GET /users +│ ├── post.js # Handles POST /users +│ └── [id]/ # Dynamic parameter +│ ├── get.js # Handles GET /users/:id +│ └── delete.js # Handles DELETE /users/:id +``` + +For example, `/routes/users/get.js` transform to `GET http://localhost:3000/users` + + +### How to define an endpoint +For file based routes, exists 2 methods to define an endpoint: + +### Object endpoint +Define a endpoint by exporting by default a object. + +example endpoint (routes/users/get.js) using object: +```javascript +export default { + // Define contexts needed by this endpoint + useContexts: ["db"], + + // Define middlewares for this endpoint + useMiddlewares: ["auth"], + + // Main handler function + fn: async (req, res, ctx) => { + const users = await ctx.db.collection("users").find().toArray() + + return { users } + } +} +``` + +### Endpoint class +Define a endpoint by exporting by default a class. + +[See Endpoint class](../classes/endpoint.md) + +example endpoint (routes/users/get.js) using class: +```javascript +export default class extends Endpoint { + // Define contexts needed by this endpoint + static useContexts = ["db"] + + // Define middlewares for this endpoint + static useMiddlewares = ["auth"] + + // Main handler function + async run(req, res, ctx) { + const users = await ctx.db.collection("users").find().toArray() + + return { users } + } +} +``` diff --git a/server/src/classes/Endpoint/index.js b/server/src/classes/Endpoint/index.js index 8fb30a2..d895a8b 100644 --- a/server/src/classes/Endpoint/index.js +++ b/server/src/classes/Endpoint/index.js @@ -4,6 +4,9 @@ export default class Endpoint { static _constructed = false static _class = true + static useContexts = null + static useMiddlewares = null + constructor(method, context) { this._constructed = true this.context = context