@openlab/deconf-api-toolkit

deconf-api-toolkit

Table of contents

• Architecture
• How does it work
• Extensions
• Development
  • setup
  • regular use
  • irregular use
  • example app
  • releasing

deconf is a set of libraries for running decentralised virtual conferences. This toolkit is a http-agnostic node.js package for creating a headless API to run a conference.

This library is currently an adaptation from digitalinteraction/climatered-api which was the API behind the climate.red virtual summit.

The purpose of this library is to take the knowledge and experience we gained from running that conference and to expose the functionality to run more conferences.

This API toolkit is being design hand-in-hand with a UI toolkit which does the same for the visual components of the conference - work in progress

Architecture

Api toolkit is designed to be framework agnostic in terms of a http lbrary (e.g. express), but it does rely on some infrastructure.

• It uses a redis cache to store conference resources which are served to users
• It uses JWT authentication to authorize access to resources and links
• It uses postgres to store attendees and track their attendance to sessions

Efforts might be made in the future to make the toolkit more agnostic but for not you can swap out modules/services by supplying something with the same interface.

How does it work

The features of the conference have been split up into interchangable modules so you can configure your own conference API with some or all of the same features.

The current modules are:

• Accounts - coming soon
• Attendance - Endpoints for tracking attendance to sessions
• Carbon - Endpoints for calculating c02 savings by hosting the conference online
• Coffee - coming soon - Endpoints for matchmaking webrtc coffee chats
• GitScraper - coming soon - utilities for fetching, parsing & validating static content from git
• Migrate - utilities for running migrations on the postgres database
• Interpret - coming soon - Endpoints for running real-time audio interpretation
• Schedule - Endpoints for the conference schedule resources

All http-releated modules return a HttpResponse instance which you can bind to your own http framework (express, koa, etc).

class HttpResponse {
  constructor(
    public status: number,
    public body: any = '',
    public headers: any = {}
  ) {}
}

These modules internally use a set of services, some of which are provided but all can be overidden to add your own implementations

• Authentication - for authenticating requests / sockets
• Conference - for pulling schedule resources from redis
• Email - user-provided for sending emails to users i.e. when logging in
• I18n - for loading translations and accessing them
• Jwt - for signing and verifying Json Web Tokens
• Postgres - for access to postgres with client-pooling
• Query - for querying data from postgres
• Redis - for fetching data from redis
• Url - user provided for creating urls for resources / pages

Services and Modules internally use structs which are written using superstruct. see src/structs

Extensions

Some services you need to provide yourself as there is no agnostic way of implementing them and you can swap out any modules or services if you want to work differently.

Services are the internal reusable logic and modules are public-facing code that can be imported and used.

The components of the toolkit rely on dependency injection to talk to each other. A module or service is defined in three parts, say we were adding a Random module:

// First is the service interface
interface RandomModule {
  generateFloat(min: number, max: number): number
}

// Second is the service's options
// lets say it relies on a made up "Entropy" service
interface RandomOptions {
  entropy: EntropyService
}

// Third is the constructor for the module
function createRandomModule(options: RandomOptions): RandomModule {
  return {
    generateFloat(min, max) {
      return min + Math.floor(entropy.generate() * (max - min))
    },
  }
}

Development

setup

npm install

regular use

npm test

irregular use

# manually run prettier (auto-runs on git-stage)
npm run format

# manually lint typescript
npm run lint

# generate coverage and open the report
npm run coverage
open coverage/lcov-report/index.html

# generate the table of contents in this readme
npm run readme-toc

# manually compile TypeScript
npm run build

example app

# Run the docker stack and start the server
# -> Redis is on redis://localhost:6379
# -> Postgres is on postgres://user:secret@localhost:5432/user
# -> Server runs on http://localhost:3000
docker-compose up -f examples/docker-compose.yml

releasing

Git commits to this repo must follow conventional commits which lets us auto-generate the CHANGELOG.md and decide the next version of the package.

# generate a new version and publish it
npm release

---

setup with puggle