@openreachtech/renchan

v2.11.0

Published

2 days ago

Renchan Core module for Application.

0High
0Medium
0Low

renchan-core

Overview

A framework based on Express that generates template-style endpoints for both GraphQL servers and RESTful API servers.

Installation

Node.js is required. If you haven't installed it yet, please do so first.

| Tool | Version | | :-- | :-- | | Node.js | >=20.0.0 | | npm | ^10.9.0 |

Command

You can install renchan with the following command:

npm install @openreachtech/renchan

GraphQL Server

The GraphQL Server provides templates for necessary implementation points in your application.

The file structure required to build a single GraphQL endpoint is shown below.

Structure when the endpoint is https://example.com/graphql-my-app:

server/
└── graphql/
    ├── context/
    │   ├── MyAppGraphqlContext.js
    │   └── MyAppGraphqlShare.js
    ├── resolvers/
    │   └── my-app/
    │       ├── AlphaQueryResolver.js
    │       ├── BetaQueryResolver.js
    │       ├── GammaMutationResolver.js
    │       ├── DeltaMutationResolver.js
    │       └── ︙
    ├── schemas/
    │   └── my-app.graphql
    └── MyAppGraphqlServerEngine.js

Class Structure

`GraphqlServerEngine`

A class that inherits from BaseGraphqlServerEngine. It allows template-style implementation of essential processes for Express + GraphQL server.

`GraphqlServerEngine.get:config`

The GraphQL server environment settings are defined within the ServerEngine class.

class MyAppGraphqlServerEngine extends BaseGraphqlServerEngine {
  ...

  .get:config () {
    return {
      graphqlEndpoint: '/graphql-my-app',
      staticPath: rootPath.to('public/'),
      schemaPath: rootPath.to('app/server/graphql/schemas/my-app.graphql'),
      actualResolversPath: rootPath.to('app/server/graphql/resolvers/my-app/'),
      stubResolversPath: null,
      redisOptions: null,
    }
  }

  ...
}

| Field | Description | | :-- | :-- | | graphqlEndpoint | Specifies the path that becomes the GraphQL endpoint | | staticPath | Specifies the folder for static files accessible from the same origin as the GraphQL server | | schemaPath | Specifies the GraphQL schema fileWhen specifying a folder, it reads the concatenated schema files within | | actualResolversPath | Specifies the folder path where Resolver classes are definedFiles in the folder are imported recursively | | stubResolversPath | Specifies the folder path for stub Resolver classesFiles in the folder are imported recursively | | maxDocumentDepth | Specifies the depth a GraphQL document may reachCounted per top-level selection, from the selection itself down to its deepest fieldWatched on production alone by default, and only where it is an integer of one or moreWhen omitted, the depth is not capped | | redisOptions | When using Redis for Subscription, specify host and port in this field |

`GraphqlServerEngine#collectRequestValidators()`

Before a GraphQL document is executed, the request validators below are applied to it. Both are watched on production alone by default.

Introspection is therefore refused on production.

To watch maxDocumentDepth in other environments as well, override DocumentTooDeepGraphqlRequestValidator.shouldSkipValidation() in a derived class to return false, and list that class in .collectGraphqlRequestValidatorCtors() of the engine.

class EveryEnvironmentDocumentTooDeepGraphqlRequestValidator extends DocumentTooDeepGraphqlRequestValidator {
  static shouldSkipValidation ({ engine }) {
    return false
  }
}

class MyAppGraphqlServerEngine extends BaseGraphqlServerEngine {
  ...

  static collectGraphqlRequestValidatorCtors () {
    return [
      EveryEnvironmentDocumentTooDeepGraphqlRequestValidator,
      IntrospectionAccessedGraphqlRequestValidator,
    ]
  }

  ...
}

A refusal is returned with the error code declared under its error name in .get:standardErrorCodeHash. When the name is not declared there, the code of Unknown is returned.

class MyAppGraphqlServerEngine extends BaseGraphqlServerEngine {
  ...

  static get standardErrorCodeHash () {
    return {
      Unknown: '100.X000.001',
      ...
      IntrospectionAccessed: '103.X000.002',
      DocumentTooDeep: '103.X000.003',
    }
  }

  ...
}

`GraphqlContext`

A class that inherits from BaseGraphqlContext. Used when generating context instances passed to all Resolvers.

Override BaseGraphqlContext.findUser() to generate user entities for authentication/authorization per GraphQL API request. It receives expressRequest, engine and accessToken.

The following can be obtained from the context instance passed to all Resolvers:

`GraphqlShare`

A class that inherits from BaseGraphqlShare. Acts as a hub for instances that need to be shared across all Resolvers.

For example, storing a PubSub class instance (commonly used in Subscriptions) as a Share class property allows it to be shared across Resolver calls.

If your application doesn't need to share any instances, define an empty class that inherits from BaseGraphqlShare.

`ExpressMiddleware`

A class that inherits from BaseExpressMiddleware. Composes one Express middleware in #composeMiddleware(), and reaches the engine through #engine and its share through #get:share.

class CorsExpressMiddleware extends BaseExpressMiddleware {
  composeMiddleware () {
    return cors()
  }
}

class MyAppGraphqlServerEngine extends BaseGraphqlServerEngine {
  static get ExpressMiddleware () {
    return [
      CorsExpressMiddleware,
    ]
  }

  collectMiddleware () {
    return [
      ...this.composeExpressMiddleware(),
    ]
  }
}

`Resolver`

Define one Resolver class per schema field.

Define the following members:

Setting up the GraphQL Server

Implementation example of a bootstrap file to start the server:

import {
  GraphqlServerBuilder,
} from '@openreachtech/renchan'

import MyAppGraphqlServerEngine from './server/graphql/MyAppGraphqlServerEngine.js'

const builder = await GraphqlServerBuilder.createAsync({
  Engine: MyAppGraphqlServerEngine,
})

builder.buildHttpServer()
  .listen(4000)

RESTful API Server

The RESTful API Server provides templates for necessary implementation points in your application.

The file structure required to build a group of RESTful API endpoints is shown below.

Structure when the endpoints are served under https://example.com/v1:

server/
└── restfulapi/
    ├── contexts/
    │   ├── MyAppRestfulApiContext.js
    │   └── MyAppRestfulApiShare.js
    ├── renderers/
    │   └── v1/
    │       ├── get/
    │       │   ├── AlphaGetRenderer.js
    │       │   └── BetaGetRenderer.js
    │       ├── post/
    │       │   ├── GammaPostRenderer.js
    │       │   └── DeltaPostRenderer.js
    │       └── ︙
    └── MyAppRestfulApiServerEngine.js

Class Structure

`RestfulApiServerEngine`

A class that inherits from BaseRestfulApiServerEngine. It allows template-style implementation of essential processes for Express + RESTful API server.

`RestfulApiServerEngine.get:config`

The RESTful API server environment settings are defined within the ServerEngine class.

class MyAppRestfulApiServerEngine extends BaseRestfulApiServerEngine {
  ...

  static get config () {
    return {
      pathPrefix: '/v1',
      renderersPath: rootPath.to('app/server/restfulapi/renderers/v1/'),
      staticPath: rootPath.to('public/'),
    }
  }

  ...
}

| Field | Description | | :-- | :-- | | pathPrefix | Specifies the path that prefixes the route path of every RendererSpecify null when the routes take no prefix | | renderersPath | Specifies the folder path where Renderer classes are definedFiles in the folder are imported recursively | | staticPath | Specifies the folder for static files accessible from the same origin as the RESTful API serverAttach it with express.static() in #collectMiddleware() |

`RestfulApiContext`

A class that inherits from BaseRestfulApiContext. Used when generating context instances passed to all Renderers.

Override BaseRestfulApiContext.findUser() to generate user entities for authentication/authorization per RESTful API request. It receives expressRequest, engine and accessToken.

The following can be obtained from the context instance passed to all Renderers:

`RestfulApiShare`

A class that inherits from BaseRestfulApiShare. Acts as a hub for instances that need to be shared across all Renderers.

If your application doesn't need to share any instances, define an empty class that inherits from BaseRestfulApiShare.

`ExpressMiddleware`

A class that inherits from BaseExpressMiddleware. Composes one Express middleware in #composeMiddleware(), and reaches the engine through #engine and its share through #get:share.

class CorsExpressMiddleware extends BaseExpressMiddleware {
  composeMiddleware () {
    return cors()
  }
}

class MyAppRestfulApiServerEngine extends BaseRestfulApiServerEngine {
  static get ExpressMiddleware () {
    return [
      CorsExpressMiddleware,
    ]
  }

  collectMiddleware () {
    return [
      ...this.composeExpressMiddleware(),
    ]
  }
}

`Renderer`

Define one Renderer class per route.

A Renderer inherits from the base class of the HTTP method it answers on — BaseGetRenderer, BasePostRenderer, BasePutRenderer, BasePatchRenderer, BaseDeleteRenderer, BaseHeadRenderer, BaseOptionsRenderer, BaseConnectRenderer, BaseTraceRenderer — and that base class is what defines .get:method.

Define the following members:

Renderer classes are registered nowhere. Every class under .get:config.renderersPath that inherits from BaseRenderer is imported recursively, and each of them is mounted on the route .get:config.pathPrefix + .get:routePath, with the HTTP method of .get:method.

So the Renderer below answers GET /v1/alpha/:id when pathPrefix is /v1. The folder a Renderer sits in takes no part in its route.

import {
  BaseGetRenderer,
  RestfulApiResponse,
} from '@openreachtech/renchan'

export default class AlphaGetRenderer extends BaseGetRenderer {
  static get routePath () {
    return '/alpha/:id'
  }

  async render ({
    body,
    query,
    context,
    request,
  }) {
    return RestfulApiResponse.create({
      statusCode: 200,
      content: {
        id: request.pathParameterHash.id,
      },
    })
  }
}

Setting up the RESTful API Server

Implementation example of a bootstrap file to start the server:

import {
  RestfulApiServerBuilder,
} from '@openreachtech/renchan'

import MyAppRestfulApiServerEngine from './server/restfulapi/MyAppRestfulApiServerEngine.js'

const builder = await RestfulApiServerBuilder.createAsync({
  Engine: MyAppRestfulApiServerEngine,
})

builder.buildHttpServer()
  .listen(4000)

License

This project is released under the Apache License 2.0.

For more details, please see in the LICENSE file.

Contributing

Bug reports, feature requests, and code contributions are welcome.

Feel free to contact us through GitHub Issues.

git clone https://github.com/openreachtech/renchan-core.git
cd renchan-core
npm install
npm run lint
npm test

Developers

Open Reach Tech Inc.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

renchan-core

Overview

Installation

Command

GraphQL Server

Class Structure

GraphqlServerEngine

GraphqlServerEngine.get:config

GraphqlServerEngine#collectRequestValidators()

GraphqlContext

GraphqlShare

ExpressMiddleware

Resolver

Setting up the GraphQL Server

RESTful API Server

Class Structure

RestfulApiServerEngine

RestfulApiServerEngine.get:config

RestfulApiContext

RestfulApiShare

ExpressMiddleware

Renderer

Setting up the RESTful API Server

License

Contributing

Developers

Copyright

`GraphqlServerEngine`

`GraphqlServerEngine.get:config`

`GraphqlServerEngine#collectRequestValidators()`

`GraphqlContext`

`GraphqlShare`

`ExpressMiddleware`

`Resolver`

`RestfulApiServerEngine`

`RestfulApiServerEngine.get:config`

`RestfulApiContext`

`RestfulApiShare`

`ExpressMiddleware`

`Renderer`