[FEATURE] The future of glee as a framework

[KhudaDad414]

Context:

following #795
Glee is a great tool for API-first development, but it hasn't gained much traction. I believe the issues are mostly::

• Shallow learning curve: due to limiting the user to use rigid file structure for operations, lifecycles, and authentication.
• Difficulty in managing a global state: Each operation/lifecycle function must be in its file, it makes having a centralized state harder.
• Can only be used in the node environment

Proposed Solution:

Get Rid of File-based routing: To be honest, I don't see why we are forcing users to have functions and lifecycles folders and follow a rigid file-based operation handlers structure.

Frameworks like Next.js use folders since they have a good excuse for it, (ie, file-based routing) but Glee is more like Express.js, at the end user only needs to pass operation handlers and we take care of the rest.

Adapters should be separate packages: By having adapters as separate packages their development can be more streamlined, and they can be maintained by their respective contributors. plus user can write their adapter and plug it in.

It will help us run glee in the browser as well as the node environment, given the provided adapter supports it.

How should it look like:

an example demonstrating how the glee interface should look like:

import { Parser } from '@asyncapi/parser';
import { WSServerAdapter } from 'Aasyncapi/glee-adapters-ws';
import { Glee } from '@asyncapi/glee';
import type { Context, Message } from '@asyncapi/glee';


//parse the asyncapi file
const parser = new Parser()
const file = await Bun.file('asyncapi.yaml').text()
const {document} = await parser.parse(file)
if(!document) throw new Error('Invalid asyncapi file')

//Initialize the Glee instance
//GleeOptions will include the configuration that we do with glee.config.js and .env file.
const glee = new Glee(document, {}: GleeOptions)

//Add the adapter
glee.use(new WSServerAdapter({}: AdapterOptions))

//Add the operation handler
glee.use('hello', (message: Message, context: Context) => {
  console.log('Received:', message.payload)
  //this is how we reply to the message
  message.reply('world')
  //this is how we send a message to a specific server
  context.send('server-id', 'message to server-id')
})


//Add event listeners
glee.on('connection:open', ({connection, serverId}) => {
  // A connection has been established to one of the servers
})

glee.on('connection:close', ({connection, serverId}) => {
  // A connection has been closed
})


glee.connect()

Adapters are required to Extend this class:

• the events that they can emit are standardised.
• The protocols and the environment that they can run should be specified.

import { EventEmitter } from 'events'
import { GleeError } from '../Errors'
import type { ServerInterface } from '@asyncapi/parser'
import { AsyncAPIServer } from '../ServerWrapper'
import type { Message } from '../Message'
import type { WebSocketConnection } from './ws/server'



interface AdapterEvents {
  'connection:open': (connection: WebSocketConnection) => void,
  'connection:close': (connection: WebSocketConnection) => void,
  'server:listening': () => void
  'server:shutdown': () => void
  'error': (error: GleeError) => void,
  'message': (message: Message) => void,
}


interface AdapterEvent {
  connection: Connection
  serverId: string
}

enum Environment {
  BROWSER = 'browser',
  NODE = 'node'
}

export class Adapter extends EventEmitter {

  protected _asyncAPIServer: AsyncAPIServer

  emit<U extends keyof AdapterEvents>(event: U, ...args: Parameters<AdapterEvents[U]>): boolean {
    return super.emit(event, ...args)
  }
  on<U extends keyof AdapterEvents>(event: U, listener: AdapterEvents[U]): this {
    return super.on(event, listener)
  }


  constructor(server: ServerInterface) {
    super()
    this._asyncAPIServer = new AsyncAPIServer(server)
  }

  async connect(): Promise<Adapter> {
    try {
      return this._connect()
    } catch (e) {
      const errorMessage = `Unable to establish a connect to ${this.name()}.`
      this.emitError(new GleeError({name: 'SERVER_SERVE_ERROR', message: errorMessage, cause: e}))
    }
    return this
  }
  
  protected _connect(): Adapter{
    throw new Error('Method not implemented.')
  }

  name(): string {
    throw new Error('Method not implemented.')
  }

  send(message: Message): void {
    throw new Error('Method not implemented.')
  }

  protected emitMessage(message: Message) {
    this.emit('message', message)
  }

  protected emitServerListening() {
    this.emit('server:listening')
  }

  protected emitServerShutdown() {
    this.emit('server:shutdown')
  }

  protected emitConnectionOpen = ({connection}: AdapterEvent) => {
    this.emit('connection:open', connection)
  }

  protected emitConnectionClose = ({connection}: AdapterEvent) => {
    this.emit('connection:close', connection)
  }

  emitError(error: GleeError) {
    this.emit('error', error)
  }

  supportedProtocols(): string[] {
    throw new Error('Method not implemented.')
  }

  supportedEnvironments(): Environment[] {
    throw new Error('Method not implemented.')
  }

} 

Technical changes:

• Convert glee to a monorepo: we can release the Adapters separately and utilities like validators can have their package.
• use PNPM: it works better with mono repo.

[oviecodes]

@KhudaDad414 what's the update, how do we proceed on this issue?

[KhudaDad414]

@oviecodes I am currently waiting for some feedback from the community. Maybe we can discuss it in the DX working group.

[Souvikns]

I like the idea of removing file-based routing, as by removing it we can use glee on the browser as well.

glee.use(new WSServerAdapter({}: AdapterOptions))

I think we should use some adapters out of the box, and the user can over-write them or add new adapters, so no idea to create a mono-repo.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️