@yopdev/dev-server 3.0.1 → 3.0.2-RC1

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,33 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/__tests__/bootstrap.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "@jest/globals";
+import { DevServer, allOf } from "../src";
+import { Service } from "../src/services";
+import { fail } from "assert";
+
+describe("dev server", () => {
+    it("bootstraps with defaults and an empty service", async () => {
+        const name = 'bootstrap';
+        const tested = await new DevServer(name, new Service({
+            name: 'service',
+            start: async () => Promise.resolve(),
+            stop: async () => Promise.resolve(),
+        })).start()
+        return expect(tested.name).toEqual(name)
+    })
+
+    it("calls service cleanup when init fails", async () => {
+        let called = false;
+        try {
+            await new DevServer('bootstrap', new Service({
+                name: 'failing-root',
+                start: async () => Promise.reject(new Error('fail!')),
+                stop: async () => Promise.resolve(called = true).then(),
+            })).start()
+            fail('should have failed')
+        } catch (e) {
+            return expect(called)
+                .toStrictEqual(true)
+        }
+    })
+
+    it("calls service cleanups on all components", async () => {
+        let calledOnParent = false;
+        let calledOnSibling = false;
+        let calledOnFailing = false;
+        try {
+            await new DevServer('bootstrap', allOf([
+                new Service({
+                    name: 'parent',
+                    start: async () => Promise.resolve(),
+                    stop: async () => Promise.resolve(calledOnParent = true).then(),
+                }), allOf([
+                    new Service({
+                        name: 'failing-nested',
+                        start: async () => Promise.reject(new Error('fail!')),
+                        stop: async () => Promise.resolve(calledOnFailing = true).then(),
+                    }),
+                    new Service({
+                        name: 'sibling',
+                        start: async () => Promise.resolve(),
+                        stop: async () => Promise.resolve(calledOnSibling = true).then(),
+                    }),
+                ])
+            ])).start()
+            fail('should have failed')
+        } catch (e) {
+            return expect([calledOnParent, calledOnFailing, calledOnSibling])
+                .toStrictEqual([true, true, true])
+        }
+    })
+
+    it("propagates the exception from the failing service", async () => {
+        const error = new Error('fail!')
+        try {
+            await new DevServer('bootstrap', allOf([
+                new Service({
+                    name: 'parent',
+                    start: async () => Promise.resolve(),
+                    stop: async () => Promise.resolve(),
+                }), allOf([
+                    new Service({
+                        name: 'failing-nested',
+                        start: async () => Promise.reject(error),
+                        stop: async () => Promise.resolve(),
+                    }),
+                    new Service({
+                        name: 'sibling',
+                        start: async () => Promise.resolve(),
+                        stop: async () => Promise.resolve(),
+                    }),
+                ])
+            ])).start()
+            fail('should have failed')
+        } catch (e) {
+            return expect(e)
+                .toStrictEqual(error)
+        }
+    })
+})

package/__tests__/deferred.test.ts

@@ -0,0 +1,86 @@
+import { describe, test, expect } from "@jest/globals";
+import { DevServer, DevServerConfig, Service, promised } from "../src";
+import { StartedNetwork } from "testcontainers";
+import { Sqs } from "../src/sqs";
+import { Sns } from "../src/sns";
+import { S3 } from "../src/s3";
+import { DynamoDb } from "../src/dynamodb";
+import { fail } from "assert";
+
+describe("a promised service", () => {
+    test("calls start with devserver config", () => {
+        const aws = {
+            region: 'region',
+            endpoint: 'http://localhost',
+            credentials: {
+                accessKeyId: 'aki',
+                secretAccessKey: 'sak',
+            },
+        }
+        const c: DevServerConfig = {
+            raw: aws,
+            network: new StartedNetwork(undefined, 'network', undefined),
+            sqs: new Sqs(aws),
+            sns: new Sns(aws),
+            s3: new S3(aws),
+            dynamo: new DynamoDb(aws),
+            eventsProxy: {
+                topic: {
+                    arn: 'arn:...',
+                },
+            },
+        }
+        return expect(
+            promised(async (cfg: DevServerConfig) => Promise.resolve(new Service(
+                {
+                    name: 'resolved',
+                    start: (config) => Promise.resolve(cfg === config),
+                    stop: () => Promise.resolve(),
+                }
+            ))
+            ).start(c)
+        )
+            .resolves.toStrictEqual(true)
+    })
+
+    test("calls the stop routine on failure starting promised service", async () => {
+        const error = new Error('failed starting service')
+        let stopped = false;
+        try {
+            await new DevServer('fail-on-start', promised(
+                () => Promise.resolve(
+                    new Service({
+                        name: 'fail-on-start',
+                        start: async () => Promise.reject(error),
+                        stop: async () => { stopped = true },
+                    }))
+            )).start()
+            fail('should have thrown exception')
+        } catch (e) {
+            return expect(stopped)
+                .toStrictEqual(true)
+        }
+    })
+
+    test("calls the cleanup routine on failure constructing promised service", async () => {
+        const error = {
+            cleanup: async () => stopped = true
+        }
+        let stopped = false;
+        try {
+            await new DevServer('fail-on-construct', promised(
+                () => Promise.resolve(
+                    new Service({
+                        name: 'fail-on-construct',
+                        start: async () => Promise.resolve(),
+                        stop: async () => Promise.resolve(),
+                    }))
+                    .then(() => Promise.reject(error)),
+            )).start()
+            fail('should have thrown exception')
+        } catch (e) {
+            return expect(stopped)
+                .toStrictEqual(true)
+        }
+    })
+})

package/__tests__/event-proxy.test.ts

@@ -0,0 +1,42 @@
+import { describe, test, expect } from "@jest/globals";
+import { allOf, DevServer, eventsProxy, Service } from "../src";
+import { EventHandler } from "../src/event-proxy";
+import { Sns } from "../src/sns";
+
+describe("the event proxy", () => {
+    test("handles an implementation error gracefully", async () => {
+        let sns: Sns;
+        let topic: { arn: string; };
+        let invoked = false;
+        const handler: EventHandler = {
+            name: 'fail',
+            handler: async () => {
+                invoked = true;
+                return Promise.reject();
+            },
+            matcher: () => true,
+        }
+        const devServer = await new DevServer(
+            'events-proxy',
+            allOf([
+                new Service({
+                    name: 'config-capture',
+                    start: (config) => {
+                        sns = config.sns;
+                        topic = config.eventsProxy.topic;
+                        return Promise.resolve()
+                    },
+                    stop: () => Promise.resolve(),
+                }),
+                eventsProxy('test', {
+                    handlers: [handler]
+                }),
+            ])
+        ).start();
+        return expect(sns.publish(topic, '{}')
+                .then(() => new Promise(resolve => setTimeout(resolve, 200)))
+                .then(() => invoked)
+                .finally(() => devServer.stop())
+        ).resolves.toStrictEqual(true)
+    })
+})

package/__tests__/lambda-http-proxy.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect } from "@jest/globals";
+import { DevServer } from "../src";
+import { UNAUTHORIZED, newLambdaHttpProxy } from "../src/lambda-http-proxy";
+import axios from 'axios';
+import { v2 } from "../src/mappers";
+
+describe("the lambda http proxy", () => {
+    const payloadVersionV2Mapper = v2().mapper;
+
+    it("invokes the handler with the heaviest route", async () => {
+        let endpoint: string
+        const tested = await new DevServer('lambda-http-proxy', newLambdaHttpProxy(
+            'service',
+            {
+                settings: { protocol: 'http:', host: '127.0.0.1', port: undefined },
+                routes: [
+                    { method: /GET/, path: /\/a\/.*\/b\/.*\/c/, weight: 3, handler: () => Promise.resolve({ statusCode: 200, body: '' }) },
+                    { method: /GET/, path: /\/a\/.*\/b\/.*/, weight: 2, handler: () => Promise.resolve({ statusCode: 400, body: '' }) },
+                    { method: /GET/, path: /\/a\/.*/, weight: 2, handler: () => Promise.resolve({ statusCode: 400, body: '' }) },
+                ],
+                mapper: payloadVersionV2Mapper,
+            },
+            async (url) => { endpoint = url; }
+        )).start()
+        return expect(axios.get(`${endpoint}a/1/b/2/c`)
+            .then(r => r.status)
+            .finally(async () => tested.stop())
+        )
+            .resolves
+            .toEqual(200)
+    })
+
+    it("supports a single 'catch all' route", async () => {
+        let endpoint: string
+        const tested = await new DevServer('lambda-http-proxy', newLambdaHttpProxy(
+            'service',
+            {
+                settings: { protocol: 'http:', host: '127.0.0.1', port: undefined },
+                routes: [
+                    { method: /.*/, path: /.*/, weight: 0, handler: () => Promise.resolve({ statusCode: 200, body: 'handled!' }) },
+                ],
+                mapper: payloadVersionV2Mapper,
+            },
+            async (url) => { endpoint = url; }
+        )).start()
+        return expect(axios.post(`${endpoint}find-me`)
+            .then(r => ({ status: r.status, body: r.data }))
+            .finally(async () => tested.stop())
+        )
+            .resolves
+            .toStrictEqual({ status: 200, body: 'handled!' })
+    })
+
+    it("returns unauthorized when the authorizer rejects", async () => {
+        let endpoint: string
+        const tested = await new DevServer('lambda-http-proxy', newLambdaHttpProxy(
+            'service',
+            {
+                settings: { protocol: 'http:', host: '127.0.0.1', port: undefined },
+                routes: [
+                    { method: /.*/, path: /.*/, weight: 0, handler: () => Promise.resolve({ statusCode: 200, body: 'handled!' }), authorizer: () => Promise.reject(UNAUTHORIZED) },
+                ],
+                mapper: payloadVersionV2Mapper,
+            },
+            async (url) => { endpoint = url; }
+        )).start()
+        return expect(axios.get(endpoint, { validateStatus: () => true })
+            .then(r => r.status)
+            .finally(async () => tested.stop())
+        )
+            .resolves
+            .toEqual(401)
+    })
+
+    it("triggers the fallback handler when no route matches a request", async () => {
+        let endpoint: string
+        const tested = await new DevServer('lambda-http-proxy', newLambdaHttpProxy(
+            'service',
+            {
+                settings: { protocol: 'http:', host: '127.0.0.1', port: undefined },
+                routes: [
+                    { method: /.*/, path: /\a/, weight: 0, handler: () => Promise.resolve({ statusCode: 200, body: 'handled!' }) },
+                ],
+                mapper: payloadVersionV2Mapper,
+            },
+            async (url) => { endpoint = url; }
+        )).start()
+        return expect(axios.get(`${endpoint}b`, { validateStatus: () => true })
+            .then(r => ({ status: r.status, body: r.data }))
+            .finally(async () => tested.stop())
+        )
+            .resolves
+            .toStrictEqual({ status: 404, body: 'no route found to handle GET to /b' })
+    })
+
+    it("handler has access to the context", async () => {
+        const expectedContext = 'hello world!'
+        let endpoint: string
+        const tested = await new DevServer('lambda-http-proxy', newLambdaHttpProxy(
+            'service',
+            {
+                settings: { protocol: 'http:', host: '127.0.0.1', port: undefined },
+                routes: [
+                    {
+                        method: /.*/,
+                        path: /\a/,
+                        weight: 0,
+                        handler: (_: unknown, context: string) => Promise.resolve({ statusCode: 200, body: context })
+                    },
+                ],
+                context: () => expectedContext,
+                mapper: payloadVersionV2Mapper,
+            },
+            async (url) => { endpoint = url; }
+        )).start()
+        return expect(axios.get(`${endpoint}a`)
+            .then(r => r.data)
+            .finally(async () => tested.stop())
+        )
+            .resolves
+            .toStrictEqual(expectedContext)
+    })
+
+    it("can set cookies", async () => {
+        let endpoint: string
+
+        const handler = async (event: object, context: unknown) => {
+            return {
+                statusCode: 200,
+                cookies: ['galletita=criollita'],
+            }
+        };
+
+        const tested = await new DevServer('lambda-http-proxy', newLambdaHttpProxy(
+            'service',
+            {
+                settings: { protocol: 'http:', host: '127.0.0.1', port: undefined },
+                routes: [
+                    { method: /GET/, path: /\/a/, weight: 0, handler: handler },
+                ],
+                mapper: payloadVersionV2Mapper,
+            },
+            async (url) => { endpoint = url; }
+        )).start();
+
+        return expect(axios.get(`${endpoint}a`)
+            .then(r => r.headers["set-cookie"])
+            .finally(async () => tested.stop())
+        ).resolves.toContain('galletita=criollita')
+    })
+
+    it("can read cookies", async () => {
+        let endpoint: string
+
+        const handler = async (event: object, context: unknown) => {
+            return {
+                statusCode: 200,
+                body: event["headers"].cookie,
+            }
+        };
+
+        const tested = await new DevServer('lambda-http-proxy', newLambdaHttpProxy(
+            'service',
+            {
+                settings: { protocol: 'http:', host: '127.0.0.1', port: undefined },
+                routes: [
+                    { method: /GET/, path: /\/a/, weight: 0, handler: handler },
+                ],
+                mapper: payloadVersionV2Mapper,
+            },
+            async (url) => { endpoint = url; }
+        )).start();
+
+        return expect(axios.get(`${endpoint}a`, { headers: { cookie: ['galletita=criollita'] } })
+            .then(r => r.data)
+            .finally(async () => tested.stop())
+        ).resolves.toContain('galletita=criollita')
+    })
+})

package/jest.config.js

@@ -0,0 +1,7 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: "ts-jest",
+  testPathIgnorePatterns: ["/dist/"],
+  testRegex: "/__tests__/.*$",
+  testTimeout: 60000,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yopdev/dev-server",
-  "version": "3.0.1",
+  "version": "3.0.2-RC1",
   "scripts": {
     "compile": "tsc",
     "pretest": "npm run compile",
@@ -35,8 +35,5 @@
   },
   "main": "dist/src/index.js",
   "exports": "./dist/src/index.js",
-  "types": "dist/src/index.d.ts",
-  "files": [
-    "dist/src"
-  ]
+  "types": "dist/src/index.d.ts"
 }

package/src/assert.ts

@@ -0,0 +1,4 @@
+export function assertNotUndefined<T>(value: T | undefined, message = 'value is undefined'): T {
+    if (value === undefined) throw new Error(message);
+    return value;
+}

package/src/cloudformation-dynamodb-table.ts

@@ -0,0 +1,97 @@
+import { Callback, Lifecycle, Service } from './services';
+import { AttributeDefinition, CreateTableCommand, GlobalSecondaryIndex, KeySchemaElement, UpdateTimeToLiveCommand } from '@aws-sdk/client-dynamodb';
+import { CLOUDFORMATION_SCHEMA } from 'js-yaml-cloudformation-schema';
+import { load } from 'js-yaml';
+import { readFileSync } from 'fs';
+import { DevServerConfig } from './config';
+import { Logger, LoggerFactory } from '@yopdev/logging';
+import { newDynamoDbTable } from './dynamodb';
+
+export const newDynamoDbTableFromCloudFormationTemplate = (
+    name: string,
+    config: DynamoDbTableCloudFormationConfig,
+    callback?: Callback<string>,
+): Service<string> => new Service(new DynamoDbTableCloudFormation(
+    name,
+    config.template,
+    config.resource,
+    config.tableName,
+    config.throughput
+), callback)
+
+class DynamoDbTableCloudFormation implements Lifecycle<string> {
+    private readonly LOGGER: Logger
+    private readonly tableName: (name: string) => string;
+
+    constructor(
+        readonly name: string,
+        private readonly template: (name: string) => string,
+        private readonly resource: string,
+        tableName: (name: string) => string,
+        private readonly throughput: Throughput,
+    ) {
+        this.LOGGER = LoggerFactory.create(`CFN:DYNAMO[${name}]`)
+        this.tableName = tableName ? tableName : (name: string) => { throw new Error(`table name not specified on ${name}`) }
+    }
+
+    start = (config: DevServerConfig) => Promise.resolve(
+        this.parseTableDefinition(this.template(this.name))
+            .then((definition) => definition[this.resource].Properties)
+            .then((resource) => this.createTableCommand(resource, this.throughput)
+                .then((command) => newDynamoDbTable(this.name, {
+                    command: command,
+                    ttlAttribute: resource.TimeToLiveSpecification?.AttributeName,
+                }))))
+                .tap(() => this.LOGGER.info('configured'))
+                .then((service) => service.start(config))
+
+    stop = () => Promise.resolve()
+
+    private createTableCommand = async (definition: DynamoDbTableCloudformationDefinitionProperties, throughput: Throughput) =>
+        new CreateTableCommand({
+            TableName: definition.TableName ?? this.tableName(this.name),
+            KeySchema: definition.KeySchema,
+            AttributeDefinitions: definition.AttributeDefinitions,
+            GlobalSecondaryIndexes: definition.GlobalSecondaryIndexes?.map((gsi: GlobalSecondaryIndex) => ({
+                ...gsi,
+                ProvisionedThroughput: throughput,
+            })),
+            ProvisionedThroughput: throughput,
+        });
+
+    private parseTableDefinition = async (path: string) => (
+        load(readFileSync(path).toString(), {
+            schema: CLOUDFORMATION_SCHEMA,
+        }) as ResourcesCloudformationDefinition
+    ).Resources;
+}
+
+type DynamoDbTableCloudFormationConfig = {
+    template: (name: string) => string;
+    resource: string,
+    tableName: (name: string) => string;
+    throughput: Throughput;
+}
+
+type ResourcesCloudformationDefinition = {
+    Resources: {
+        [name: string]: {
+            Properties: DynamoDbTableCloudformationDefinitionProperties
+        }
+    };
+}
+
+type DynamoDbTableCloudformationDefinitionProperties = {
+    TableName?: string;
+    KeySchema: KeySchemaElement[];
+    AttributeDefinitions: AttributeDefinition[];
+    GlobalSecondaryIndexes?: GlobalSecondaryIndex[];
+    TimeToLiveSpecification?: TimeToLiveSpecification;
+}
+
+type TimeToLiveSpecification = {
+    AttributeName: string;
+    Enabled: boolean;
+};
+
+type Throughput = { ReadCapacityUnits: number; WriteCapacityUnits: number }

package/src/cloudformation-event-proxy.ts

@@ -0,0 +1,61 @@
+import { SQSEvent, SQSRecord } from 'aws-lambda';
+import { CloudFormationSetup, CloudFormationSetupConfig } from './cloudformation';
+import { EventHandler } from './event-proxy';
+import { DevServerConfig } from './config';
+import { Startable } from './services';
+import { Message } from '@aws-sdk/client-sqs';
+
+export const snsEventsFromCloudFormationTemplate = (
+    name: string,
+    config: CloudFormationEventsProxyConfig,
+): Startable<EventHandler[]> =>
+    new CloudFormationEventsProxy(name, config);
+class CloudFormationEventsProxy extends CloudFormationSetup<
+    {
+        SqsSubscription: {
+            BatchSize: string;
+            QueueArn: string;
+            QueueUrl: string;
+        };
+        Topic: string;
+        FilterPolicy: {
+            [name: string]: string[];
+        };
+    },
+    (event: SQSEvent) => Promise<unknown>,
+    EventHandler,
+    EventHandler[]
+> {
+    constructor(name: string, config: CloudFormationEventsProxyConfig) {
+        super(
+            name,
+            (event) => event.Type === 'SNS',
+            async (event, handler) => ({
+                name: handler.name,
+                handler: handler,
+                matcher: (_, attributes) => {
+                    const required = Object.entries(event.Properties.FilterPolicy ?? []).flatMap((entry) =>
+                        entry[1].map((value) => value + entry[0]),
+                    );
+                    if (required.length == 0) return true;
+                    const actual = Object.entries(attributes).flatMap((entry) => entry[1].Value + entry[0]);
+                    return required.filter((e) => actual.includes(e)).length > 0;
+                },
+            }),
+            config.prepare,
+            config
+        );
+    }
+
+    protected afterStart = (_name: string, _config: DevServerConfig, routes: EventHandler[]) => routes;
+
+    logHandler(handler: EventHandler): string {
+        return `detected sns handler ${handler.name}`;
+    }
+}
+
+type CloudFormationEventsProxyConfig = {
+    topic?: string,
+    mapper?: (message: Message) => SQSRecord,
+    prepare?: (config: DevServerConfig) => Promise<void>,
+} & CloudFormationSetupConfig;