@lawcket/websocket

    0.1.5 • Public • Published

    @lawcket/websocket

    Downloads Version License

    A pluggable API Gateway Lambda wrapper that mimics server websockets

    NOTE: Supports Serverless >=1.38 For pre-1.38 use @lawcket/websockets@0.1.4

    Installation

    npm install @lawcket/websocket

    or

    yarn add @lawcket/websocket

    Usage

    Servereless Project

    Configure your function to accept all routes/actions.

    Example:

    functions:
      websocket:
        handler: src/index.default
        memorySize: 3008
        events:
          - websocket:
              route: $connect
          - websocket:
              route: $disconnect
          - websocket:
              route: $default
    
    Lambda

    The lambda will need to be constructed by the @lawcket/websocket library. It modifies incoming messages and handles the federation of middleware and plugins.

    Example:

    // pre-ES6
    // const lawcket = require('@lawcket/websocket');
     
    // ES6
    import lawcket from '@lawcket/websocket';
     
    const handler = async (event, connection, publish) => {
      console.log(`Connection: ${JSON.stringify(connection, null, 2)}`);
      // publish is only available during a message event
      if (connection.event === 'message' && publish) {
        await publish({ message: 'hello from server' });
      }
    };
     
    export default lawcket({
      middleware: [],
      plugins: [],
      handler,
    });

    The lambda implementation will be called with three params; event, connection, and publish.

    event:

    • the original lambda event
    • contains header information during a CONNECT request

    connection:

    • a subset of collection info, useful for storing
    • object structure
      • event: 'close' | 'connect' | 'message'
      • connectionId: string
      • stage: string,
      • domainName: string

    publish:

    • only available during a message event
    • needs to be called asynchronously
    • supports base64, or stringifiable data
    Plugins

    Plugins mimic how the handler is called and is invoked asychronously. A good use case for this is storing connection information, or for processing connection-related tasks that do not pertain to the general flow of the lambda.

    Example:

    import lawcket from '@lawcket/websocket';
    
    // ... handler here
    
    const dynamo = async  (originalEvent, connection) => {
        if (connection.event === 'connect') {
            // store connection to dynamo
        }
        if (connection.event === 'close') {
            // remove connection from dynamo
        }
    }
    
    export default lawcket({
      middleware: [],
      plugins: [dynamo],
      handler,
    });
    

    Middleware

    Middleware are used to modify or interrupt the lambda event. An excellent use-case for this is authentication. Internally @lawcket/websocket uses a middleware to automatically parse incoming body data. Be aware, middleware are processed in-order.

    Example:

    import lawcket from '@lawcket/websocket';
    
    // ... handler here
    
    const auth = (originalEvent) => {
        const { requestContext, headers } = originalEvent;
        if (headers && headers.Authorization 
            && requestContext.eventType === 'CONNECT') {
            // check authorization here
        }
        
        // middleware must return the event if not throwing
        return originalEvent;
    }
    
    export default lawcket({
      middleware: [auth],
      plugins: [],
      handler,
    });
    

    Click here for a full example of @lawcket/websocket usage.

    Install

    npm i @lawcket/websocket

    DownloadsWeekly Downloads

    1

    Version

    0.1.5

    License

    MIT

    Unpacked Size

    6.33 kB

    Total Files

    5

    Last publish

    Collaborators

    • icarus-sullivan