Associate metadata with inflight blocks with@meta

[eladb]

We are seeing some requirements for supporting platform-level configuration in inflight "blocks".

Some examples are #3410 and #6761.

I believe that it might make sense to design dedicated support for each of the use cases above (and others in the future), but there will always be new cases where an inflight block needs to "communicate" with the platform during synthesis.

I'd like to propose that we experiment with a concept called "inflight metadata" which is basically a key/value bag associated with inflight closures and can be consumed by platform providers and respected by them.

class Foo {
  pub inflight bar() {
    // do not bundle "fsevents" into the lambda.Function
    @meta(key: "esbuild.external", value: "fsevents");
    
  }
}

let foo = new Foo();

new cloud.Function(inflight () => {
  @meta(key: "acme.lambda_layer", value: "datadog-3.x");
  foo.bar(); // <-- implicitly adds the `esbuild.external=fsevents` meta to the closure
});

Then, the cloud.Function implementation at the platform level will be able to reflect on the metadata and determine how to behave.

The proposed API (accepting a struct of key and value) allows exposing some type safe APIs by platform teams:

bring acme;

@meta(acme.LambdaLayers.addDatadog("3.x"));

[MarkMcCulloh]

The two examples given (esbuild externals and lambda layers) are not responsibilities of inflights themselves but rather the host, so it seems strange to expose them in there. "external" is debatable inflight responsibility but a cloud function in AWS vs Azure (depending on the lambda layers) don't necessarily have the same externals.

[eladb]

It's not the responsibility of the inflight closure, but it's an attribute of it, which the host may consider. The fact that the closure uses some external dependency or some lambda layer.

[MarkMcCulloh]

Where does that end?

class Foo {
  pub inflight bar() {
    @meta(key: "esbuild.external", value: "fsevents");
    @meta(key: "esbuild.module", value: "esm");
    @meta(key: "esbuild.minify", value: "true");
    @meta(key: "runtime", value: "node18");
    @meta(key: "memory", value: "1gb");
  }
}

All of these may or may not matter at runtime, and any consuming hosts may or may not support them. That seems a little chaotic.

[eladb]

Yes, this is a low level mechanism designed to unblock use cases that cross the app/platform layer. As such it can be potentially messy and abusable, but that's a classic trade off.

(think: environment variables, CDK context, k8s taints, AWS tags - all of these are very similar).

I can see a world where some of these attributes could be "elevated" into higher level APIs but at this point I'd like this tool in our toolbox and see how it behaves.

[skyrpex]

I'm with Mark here: these meta properties are host concerns so having them available inside inflights feels wrong. IMO, I'd prefer to go the other way around and allow users customize the bundling for each host:

bring cloud;

let bucket = new cloud.Bucket();

new cloud.Function(() => {
  bucket.put("hello.txt", "world");
}, esbuild: {
  external: ["fsevents"],
});

new cloud.Api(esbuild: { ... });

In addition, I'd love to have the let code = @lift(inflight) I suggested last week and allow the hosts bundle the generated inflight code at will, using esbuild or any other custom tool, and allowing users to use wing code for custom hosts.

[eladb]

As I mentioned above, associating them to the host won't work because there are many cases where the host is only determined by someone else.

Here's the use case again:

Consider I am creating a Winglib mylib that publishes the following class:

pub class MyResource {
  pub inflight fly() {
    @meta("lambda-layer", "datadog-1.2");
    globals.datadog.publish_metric(...); // <-- made up API
  }
}

Then, in another universe, an app consumes this library:

bring mylib;

let x = new mylib.MyResource();

let api = new cloud.Api();
api.get("/", inflight () => {
  x.fly();
}

There are two problems here:

1. I don't have direct access to the cloud.Function behind the cloud.Api, and maybe there's no function there at all, depending on the platform.
2. The application that consumes this library can't know that the fly() method needs the layer. It's an implementation detail of the library, not something that I expect the app to know.

[Chriscbr]

Interestingly this proposal has some parallels to Golang's struct tags (in the respect that both expose a stringly-typed annotation system of sorts)

[hasanaburayyan]

On the notes of annotations we also had this RFC started some time ago (proposing struct annotations):
#3686

[Chriscbr]

I like the overall direction being sketched out! -- especially if we imagine the macro serving as a declarative way to specify host requirements or capabilities, which serves as a complement to the "onLift" and "onLiftType" hooks we have today which specify host requirements or capabilities in an imperative way.

But IMO there is some details worth fleshing out - here are some questions on my mind:

Primary (I think the answers to these may have a large impact on the developer experience):

1. What happens if two different inflight functions are called with conflicting metadata tags? For example, perhaps one function has @meta(key: "runtime", value: "node18") and the other has @meta(key: "runtime", value: "node20")?
2. What would happen if a @meta annotation is added to an inflight function specifying a lambda layer, but the inflight function is then used in a host that's not deployed to AWS Lambda, like cloud.Service? Should an error be raised to the user? Would raising the error be the responsibility of the SDK or of cloud.Service? (Would there be any need to model metadata that needs to be handled vs metadata that doesn't need to be handled?)
3. How is metadata exposed to the inflight hosts? That is, if cloud.Function was implemented in Wing, how would it obtain all of the "metadata" associated with the inflight function and then act on it during preflight?
4. Is there a way to specify metadata that only applies to a specific platform (or set of platforms), or apply different metadata depending on the compilation platform?

Secondary (I think these are helpful to consider, but its also ok if we don't know the answer yet):

1. How would a user associate metadata with "extern" methods written in TypeScript or JavaScript?
2. How would a user associate metadata with inflight methods written in TypeScript using the Wing TypeScript framework?
3. Where can @meta statements be used? Can they be used in inflight constructors?
4. When are the expressions passed to @meta evaluated? In preflight or inflight?
5. Can @meta information be read or added by Wing platforms in any way?

[eladb]

I think we are ready to kick off an RFC.

The @meta annotations are just a way to associate some info on an inflight closure which can then be consumed from userland code (e.g. cloud.Function implementation) and react to it.

The onus is on the consuming code to define the semantics of each meta tag.

For example, cloud.Function can decide that if there are two runtime tags, it will throw an error (which probably makes sense). Alternatively, it can only fail if there is a mismatching runtime.

I think the mechanism should simply provide a way to tag inflight closures and then consume the set of tags from userland. The rest should be discussed on a case by case basis.

[Chriscbr]

Here's a sketch of the how I think I'd approach the questions I posed previously. I probably need to get into the implementation to figure out more of the details, but it should illuminate some more edge cases of the design:

1. Metadata tags will be aggregated in a way so that tags from nested inflight closures are preserved and available to the parent, but can be overridden by the parent. For example:

let fn1 = inflight () => {
  @meta(key: "runtime", value: "node18");
  log("fn1");
};

let fn2 = inflight () => {
  fn1();
};

In the example above, fn2 directly inherits the "runtime=node18" metadata tag.

let fn1 = inflight () => {
  @meta(key: "runtime", value: "node18");
  log("fn1");
};

let fn2 = inflight () => {
  @meta(key: "runtime", value: "node20");
  log("fn2");
};

let fn3 = inflight () => {
  fn1();
  fn2();
}

In the example above, a compilation error will occur because fn1 and fn2 both attempt to set the runtime metadata tag with different values. The error can be resolved by removing one of the @meta annotations, changing them to be consistent with each other, OR by adding a @meta annotation to fn3 to override the conflicting values.

2. Metadata tags will be treated as "opt-in", so if an inflight host does not implement logic for handling a given metadata tag, nothing will happen by default.

For example, if a user specifies a metadata tag like @meta(key: "acme.lambda_layer", value: "datadog-3.x") on an inflight function, and the function is used by a host (like cloud.Function) that doesn't know about the acme.lambda_layer key, the metadata will simply be ignored.

3. A new API will be supported for reading metadata tags from an inflight closure:

let fn1 = inflight () => {
  @meta(key: "runtime", value: "node18");
  log("fn1");
};

new LambdaFunction(fn1);

// impl of LambdaFunction:

class LambdaFunction {
  new(handler: inflight (event: Json) => Json) {
    let metadata = std.InflightMetadata.of(handler);
    if metadata.get("runtime") == "node18" {
      // ...
    } else if metadata.get("runtime") == "node20" {
      // ...
    }
  }
}

4. For now it's unclear how we might support conditionally adding tags based on the target platform. I've sketched some ideas below but I think this is not P1.

For inflight closures, it could be possible to add metadata after the inflight closure is defined through an explicit API:

let fn1 = inflight () => {
  log("fn1");
};

if @app.target == "tf-aws" {
  std.InflightMetadata.of(fn1).set("runtime", "node18");
} else if @app.target == "tf-azure" {
  std.InflightMetadata.of(fn1).set("runtime", "node20");
}

But for inflight methods on classes, it's unclear how this would look.

We could also imagine adding an extra key to the @meta annotation to specify that the tag is only applicable to a certain list of platforms:

let fn1 = inflight () => {
  // apply this tag if the target is TF-AWS or AWS CDK
  @meta(key: "runtime", value: "node18", platforms: ["tf-aws", "awscdk"]);
  // apply this tag only if the target is not TF-Azure
  @meta(key: "runtime", value: "node20", excludePlatforms: ["tf-azure"]);
  log("fn1");
};

5. Since @meta() is a special compiler intrinsic, the arguments to it must be string literals to start. Depending on what preflight code is generated, it could be possible to support referencing preflight values (P2):

class Foo {
  new() {
    let bucket = new cloud.Bucket();
    let api = new cloud.Api();
    api.get("/", inflight () => {
      @meta(key: "env:BUCKET_NAME", value: bucket.name); // <-- referencing bucket.name, a preflight value
      log("the bucket name is " + util.inflightEnv("BUCKET_NAME"));
    });
  }
}

Mechanically, this would get processed by the compiler into something like this (not real syntax):

class Foo {
  new() {
    let bucket = new cloud.Bucket();
    let api = new cloud.Api();
    api.get("/", (inflight () => {
      log("the bucket name is " + util.inflightEnv("BUCKET_NAME"));
    })).withMeta({
      "env:BUCKET_NAME": bucket.name
    });
  }
}

6. @meta() statements would only be allowed in inflight code. A compiler error (shown in VS Code) will be emitted if the statement is used in non-inflight code.

[eladb]

Looks good!

There's a use case for vending standard tags by libraries. Say my platform team has a bunch of lambda layers it supports, it would be nice to be able to do something like this:

bring "acme-platform" as acme;

inflight () => {
  @meta(acme.FunctionLayers.datadog());
  // do stuff
};

This static method can simply return something like a MetaTag struct with key and value fields or something.

[Chriscbr]

Mmm, good callout. You're right, to support this we'll need to allow @meta to accept an arbitrary preflight expression (something like section 5 in the previous comment)