Plugin oriented architecture

[jpbourgeon]

Architect for growth: I recommend middleware architecture like express.js or @aws-sdk. From this architecture, the core of the library will remain simple and all other aspects can be handled in the form of plugins: errors, adaptation of incompatible services (S3, etc.), ...

Are you suggesting a middleware layer for injecting interceptors into the request pipeline? I'm down for that, but i'm curious what your use-case is?

More specifically, I am suggesting a plugin architecture. By systematically decoupling the SDK into a set of well-designed plugins, we can achieve greater robustness, better control over the workflow, and more freedom for experimentation. This approach is also beneficial for building our community, as a plugin architecture facilitates community experimentation and innovation without compromising the core project.

This would be good for building our community since an extensible architecture facilitates community experimentations and innovation, and at the same time helps the maintenance team protect the core perimeter.

As I see it, our architecture would need two types of plugins: adapters and middleware.

Adapters

The Adapter design pattern is a popular pattern used to follow the Dependency Inversion Principle. By implementing a predefined interface, the adapter fulfills the expected contract and can be useful when implementing alternatives for a specific feature without impacting the main software.

For example, if we extract the fetch feature into an adapter, we can work on independent implementations such as node18-http-adapter (runtime fetch), undici-http-adapter, node-fetch-http-adapter (for node.js < 14.x), and browser-http-adapter. We can also build bun-http-adapter, deno-http-adapter, cloudflare-adapter, and more. We could, I even create an ubiquitous http-adapter that includes all of them and automatically detects and returns the right abstraction depending on the execution environment, at the cost of bundle size.

This approach would also be beneficial for maintenance (simpler packages) and bundle size. We could build simpler adapters that handle a single responsibility, instead of shipping large packages. In the previous example, if one doesn't need to support the browser and only runs inside AWS Lambdas, they could drop the http-adapter for a smaller and more suitable undici-http-adapter.

A good candidate for an adapter would be the signature-adapter: it could rely on AWS SigV4 in early versions and then switch to a better alternative later on.

Middlewares

Middleware plugins can be used to provide hooks in the default workflow of a system, allowing optional behaviour execution at runtime. This means that if a user doesn't need a particular feature, they can simply choose not to use it, keeping the system lean and fast at execution time.

Interestingly @aws-sdk introduced a middleware stack. I used it for latency measurement in the benchmark.

From the current backlog, the middleware candidates I could identify are: marshaller-middleware for dynamodb, and a logging-middleware for our benchmarking.

Example

In this example, I have omitted the proxy part for simplicity. The example declares a pseudo SDK class, extensible through adapters and middlewares. It is then instantiated with a dummy undici-http-adapter. After that, a ddb-marshaller-middleware and ddb-unmarshaller-middleware are registered as beforeRequest and afterRequest middleware respectively. Finally, the request function is called with a sample endpoint.

type Middleware = (context: Context, next: () => Promise<void>) => Promise<void>;

interface Adapter {
  fetch: (context: Context) => Promise<Response>;
}

interface SDKOptions {
  httpAdapter: Adapter;
  beforeRequestMiddlewares: Middleware[];
  afterRequestMiddlewares: Middleware[];
}

class SDK {
  private httpAdapter: Adapter;
  private pipeline: Pipeline<Middleware>;

  constructor(options: SDKOptions) {
    this.httpAdapter = options.httpAdapter;
    this.pipeline = new Pipeline(options.beforeRequestMiddlewares, options.afterRequestMiddlewares);
  }

  public async request(context: Context) {
    const requestMiddleware = async (context) => await this.httpAdapter.fetch(context);
    const { res } = await this.pipeline.run(context, requestMiddleware);
    return res;
  }
}

class Pipeline<T> {
  private middlewares: readonly T[];

  constructor(beforeMiddlewares: readonly T[], afterMiddlewares: readonly T[]) {
    this.middlewares = [...beforeMiddlewares, ...afterMiddlewares];
  }

  public async run(context: any, finalAction: (ctx: any) => Promise<any>): Promise<any> {
    const pipeline = this.middlewares.slice().reverse();
    pipeline.push(finalAction);
    let result = context;
    for (const middleware of pipeline) {
      result = await middleware(result, async () => result);
    }
    return result;
  }
}

// Example
const undiciHttpAdapter = {
  async fetch(context: Context) {
    // implementation here
    return response;
  },
};

const ddbMarshallerMiddleware: Middleware = async (context, next) => {
  // implementation here
  await next();
  return context;
};

const ddbUnmarshallerMiddleware: Middleware = async (context, next) => {
  // implementation here
  await next();
  return context;
};

const sdk = new SDK({
  httpAdapter: undiciHttpAdapter,
  beforeRequestMiddlewares: [ddbMarshallerMiddleware],
  afterRequestMiddlewares: [ddbUnmarshallerMiddleware],
});

sdk.request('/some-endpoint');

[sam-goodwin]

How do we decide between a discussion and an issue? This one seems ok as a discussion?

[sam-goodwin]

Or are discussions just better? haha

[jpbourgeon]

We use discussions freely, as if we were in a meeting, and once we have decided what to actually implement in the code we convert each point into an issue.

Let's keep issues for actual features and bugfixes. Things that we know will go into the code, with an associated PR.

Do you agree ?

[sam-goodwin]

Sounds good to me. I actually really prefer the thread concept of discussions - much more ergonomic.

My only concern would be that most people don't check discussions? Not sure if that's true or not.

[jpbourgeon]

The GitHub community has an habit of mixing both since discussions tab are fairly new. However it will never change if we stick to tradition 😉

Using this may implie some moderation in the future (moving misplaced suggestions from issues). To mitigate, we can publish discussions and issues guidelines like many projects do. And communicate in the readme.

In the end, such moderation becoming a problem would be a sign of growth and community success! We will deal with that when the time comes.