Feature: custom runtimes to define function

.changeset/long-berries-greet.md

@@ -0,0 +1,5 @@
+---
+'@aws-amplify/backend-function': minor
+---
+
+add custom provided function support to define function

packages/backend-function/API.md

@@ -6,8 +6,10 @@
 
 import { AmplifyResourceGroupName } from '@aws-amplify/plugin-types';
 import { BackendSecret } from '@aws-amplify/plugin-types';
+import { Construct } from 'constructs';
 import { ConstructFactory } from '@aws-amplify/plugin-types';
 import { FunctionResources } from '@aws-amplify/plugin-types';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
 import { LogLevel } from '@aws-amplify/plugin-types';
 import { LogRetention } from '@aws-amplify/plugin-types';
 import { ResourceAccessAcceptorFactory } from '@aws-amplify/plugin-types';
@@ -61,8 +63,11 @@ type DataClientError = {
 // @public (undocumented)
 type DataClientReturn<T> = T extends DataClientEnv ? DataClientConfig : DataClientError;
 
-// @public
-export const defineFunction: (props?: FunctionProps) => ConstructFactory<ResourceProvider<FunctionResources> & ResourceAccessAcceptorFactory & AddEnvironmentFactory & StackProvider>;
+// @public (undocumented)
+export function defineFunction(props?: FunctionProps): ConstructFactory<ResourceProvider<FunctionResources> & ResourceAccessAcceptorFactory & AddEnvironmentFactory & StackProvider>;
+
+// @public (undocumented)
+export function defineFunction(provider: (scope: Construct) => IFunction, providerProps?: ProvidedFunctionProps): ConstructFactory<ResourceProvider<FunctionResources> & ResourceAccessAcceptorFactory & StackProvider>;
 
 // @public (undocumented)
 export type FunctionBundlingOptions = {
@@ -131,6 +136,11 @@ type LibraryOptions = {
 // @public (undocumented)
 export type NodeVersion = 16 | 18 | 20 | 22;
 
+// @public (undocumented)
+export type ProvidedFunctionProps = {
+    resourceGroupName?: AmplifyResourceGroupName;
+};
+
 // @public (undocumented)
 type ResourceConfig = {
     API: {

packages/backend-function/src/factory.test.ts

@@ -20,6 +20,7 @@ import { Policy, PolicyStatement } from 'aws-cdk-lib/aws-iam';
 import fsp from 'fs/promises';
 import path from 'node:path';
 import { AmplifyUserError } from '@aws-amplify/platform-core';
+import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
 
 const createStackAndSetContext = (): Stack => {
   const app = new App();
@@ -750,4 +751,35 @@ void describe('AmplifyFunctionFactory', () => {
       );
     });
   });
+
+  void describe('provided function runtime property', () => {
+    void it('sets valid runtime', () => {
+      const lambda = defineFunction((scope) => {
+        return new NodejsFunction(scope, 'nodejs-provided', {
+          entry:
+            './packages/backend-function/src/test-assets/default-lambda/handler.ts',
+          runtime: Runtime.NODEJS_22_X,
+        });
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(lambda.stack);
+
+      template.hasResourceProperties('AWS::Lambda::Function', {
+        Runtime: Runtime.NODEJS_22_X.name,
+      });
+    });
+
+    void it('provided function defaults to oldest runtime', () => {
+      const lambda = defineFunction((scope) => {
+        return new NodejsFunction(scope, 'nodejs-provided', {
+          entry:
+            './packages/backend-function/src/test-assets/default-lambda/handler.ts',
+        });
+      }).getInstance(getInstanceProps);
+      const template = Template.fromStack(lambda.stack);
+
+      template.hasResourceProperties('AWS::Lambda::Function', {
+        Runtime: Runtime.NODEJS_16_X.name,
+      });
+    });
+  });
 });

packages/backend-function/src/factory.ts

@@ -1,8 +1,4 @@
-import {
-  FunctionOutput,
-  functionOutputKey,
-} from '@aws-amplify/backend-output-schemas';
-import { AttributionMetadataStorage } from '@aws-amplify/backend-output-storage';
+import { FunctionOutput } from '@aws-amplify/backend-output-schemas';
 import {
   AmplifyUserError,
   CallerDirectoryExtractor,
@@ -20,18 +16,18 @@ import {
   GenerateContainerEntryProps,
   LogLevel,
   LogRetention,
+  ResourceAccessAcceptor,
   ResourceAccessAcceptorFactory,
   ResourceNameValidator,
   ResourceProvider,
-  SsmEnvironmentEntry,
   StackProvider,
 } from '@aws-amplify/plugin-types';
 import { Duration, Size, Stack, Tags } from 'aws-cdk-lib';
 import { Rule } from 'aws-cdk-lib/aws-events';
 import * as targets from 'aws-cdk-lib/aws-events-targets';
-import { Policy } from 'aws-cdk-lib/aws-iam';
 import {
   CfnFunction,
+  IFunction,
   ILayerVersion,
   LayerVersion,
   Runtime,
@@ -40,16 +36,19 @@ import { NodejsFunction, OutputFormat } from 'aws-cdk-lib/aws-lambda-nodejs';
 import { Construct } from 'constructs';
 import { readFileSync } from 'fs';
 import { createRequire } from 'module';
-import { fileURLToPath } from 'node:url';
 import { EOL } from 'os';
 import * as path from 'path';
 import { FunctionEnvironmentTranslator } from './function_env_translator.js';
 import { FunctionEnvironmentTypeGenerator } from './function_env_type_generator.js';
 import { FunctionLayerArnParser } from './layer_parser.js';
 import { convertLoggingOptionsToCDK } from './logging_options_parser.js';
 import { convertFunctionSchedulesToRuleSchedules } from './schedule_parser.js';
-
-const functionStackType = 'function-Lambda';
+import {
+  ProvidedFunctionFactory,
+  ProvidedFunctionProps,
+} from './provided_function_factory.js';
+import { AmplifyFunctionBase } from './function_construct_base.js';
+import { FunctionResourceAccessAcceptor } from './resource_access_acceptor.js';
 
 export type AddEnvironmentFactory = {
   addEnvironment: (key: string, value: string | BackendSecret) => void;
@@ -70,17 +69,38 @@ export type FunctionSchedule = TimeInterval | CronSchedule;
 export type FunctionLogLevel = LogLevel;
 export type FunctionLogRetention = LogRetention;
 
-/**
- * Entry point for defining a function in the Amplify ecosystem
- */
-export const defineFunction = (
-  props: FunctionProps = {}
+export function defineFunction(
+  props?: FunctionProps
 ): ConstructFactory<
   ResourceProvider<FunctionResources> &
     ResourceAccessAcceptorFactory &
     AddEnvironmentFactory &
     StackProvider
-> => new FunctionFactory(props, new Error().stack);
+>;
+export function defineFunction(
+  provider: (scope: Construct) => IFunction,
+  providerProps?: ProvidedFunctionProps
+): ConstructFactory<
+  ResourceProvider<FunctionResources> &
+    ResourceAccessAcceptorFactory &
+    StackProvider
+>;
+/**
+ * Entry point for defining a function in the Amplify ecosystem
+ */
+// This is the "implementation overload", it's not visible in public api.
+// We have to use function notation instead of arrow notation.
+// Arrow notation does not support overloads.
+// eslint-disable-next-line no-restricted-syntax
+export function defineFunction(
+  propsOrProvider: FunctionProps | ((scope: Construct) => IFunction) = {},
+  providerProps?: ProvidedFunctionProps
+): unknown {
+  if (propsOrProvider && typeof propsOrProvider === 'function') {
+    return new ProvidedFunctionFactory(propsOrProvider, providerProps);
+  }
+  return new FunctionFactory(propsOrProvider, new Error().stack);
+}
 
 export type FunctionProps = {
   /**
@@ -477,14 +497,10 @@ class FunctionGenerator implements ConstructContainerEntryGenerator {
 }
 
 class AmplifyFunction
-  extends Construct
-  implements
-    ResourceProvider<FunctionResources>,
-    ResourceAccessAcceptorFactory,
-    AddEnvironmentFactory
+  extends AmplifyFunctionBase
+  implements AddEnvironmentFactory
 {
   readonly resources: FunctionResources;
-  readonly stack: Stack;
   private readonly functionEnvironmentTranslator: FunctionEnvironmentTranslator;
   constructor(
     scope: Construct,
@@ -493,9 +509,7 @@ class AmplifyFunction
     backendSecretResolver: BackendSecretResolver,
     outputStorageStrategy: BackendOutputStorageStrategy<FunctionOutput>
   ) {
-    super(scope, id);
-
-    this.stack = Stack.of(scope);
+    super(scope, id, outputStorageStrategy);
 
     const runtime = nodeVersionMap[props.runtime];
 
@@ -616,52 +630,18 @@ class AmplifyFunction
       },
     };
 
-    this.storeOutput(outputStorageStrategy);
-
-    new AttributionMetadataStorage().storeAttributionMetadata(
-      Stack.of(this),
-      functionStackType,
-      fileURLToPath(new URL('../package.json', import.meta.url))
-    );
+    this.storeOutput();
   }
 
   addEnvironment = (key: string, value: string | BackendSecret) => {
     this.functionEnvironmentTranslator.addEnvironmentEntry(key, value);
   };
 
-  getResourceAccessAcceptor = () => ({
-    identifier: `${this.node.id}LambdaResourceAccessAcceptor`,
-    acceptResourceAccess: (
-      policy: Policy,
-      ssmEnvironmentEntries: SsmEnvironmentEntry[]
-    ) => {
-      const role = this.resources.lambda.role;
-      if (!role) {
-        // This should never happen since we are using the Function L2 construct
-        throw new Error(
-          'No execution role found to attach lambda permissions to'
-        );
-      }
-      policy.attachToRole(role);
-      ssmEnvironmentEntries.forEach(({ name, path }) => {
-        this.functionEnvironmentTranslator.addSsmEnvironmentEntry(name, path);
-      });
-    },
-  });
-
-  /**
-   * Store storage outputs using provided strategy
-   */
-  private storeOutput = (
-    outputStorageStrategy: BackendOutputStorageStrategy<FunctionOutput>
-  ): void => {
-    outputStorageStrategy.appendToBackendOutputList(functionOutputKey, {
-      version: '1',
-      payload: {
-        definedFunctions: this.resources.lambda.functionName,
-      },
-    });
-  };
+  getResourceAccessAcceptor = (): ResourceAccessAcceptor =>
+    new FunctionResourceAccessAcceptor(
+      this,
+      this.functionEnvironmentTranslator
+    );
 }
 
 const isWholeNumberBetweenInclusive = (

packages/backend-function/src/function_construct_base.ts

@@ -0,0 +1,58 @@
+import { Construct } from 'constructs';
+import {
+  BackendOutputStorageStrategy,
+  FunctionResources,
+  ResourceAccessAcceptor,
+  ResourceAccessAcceptorFactory,
+  ResourceProvider,
+} from '@aws-amplify/plugin-types';
+import { Stack } from 'aws-cdk-lib';
+import {
+  FunctionOutput,
+  functionOutputKey,
+} from '@aws-amplify/backend-output-schemas';
+import { AttributionMetadataStorage } from '@aws-amplify/backend-output-storage';
+import { fileURLToPath } from 'node:url';
+
+const functionStackType = 'function-Lambda';
+
+/**
+ * A base class for function constructs.
+ */
+export abstract class AmplifyFunctionBase
+  extends Construct
+  implements ResourceProvider<FunctionResources>, ResourceAccessAcceptorFactory
+{
+  readonly stack: Stack;
+  abstract resources: FunctionResources;
+
+  abstract getResourceAccessAcceptor: () => ResourceAccessAcceptor;
+
+  /**
+   * Creates base function construct.
+   */
+  protected constructor(
+    scope: Construct,
+    id: string,
+    private readonly outputStorageStrategy: BackendOutputStorageStrategy<FunctionOutput>
+  ) {
+    super(scope, id);
+
+    this.stack = Stack.of(scope);
+
+    new AttributionMetadataStorage().storeAttributionMetadata(
+      Stack.of(this),
+      functionStackType,
+      fileURLToPath(new URL('../package.json', import.meta.url))
+    );
+  }
+
+  protected storeOutput = (): void => {
+    this.outputStorageStrategy.appendToBackendOutputList(functionOutputKey, {
+      version: '1',
+      payload: {
+        definedFunctions: this.resources.lambda.functionName,
+      },
+    });
+  };
+}

packages/backend-function/src/index.ts

@@ -1 +1,3 @@
 export * from './factory.js';
+import { ProvidedFunctionProps } from './provided_function_factory.js';
+export { ProvidedFunctionProps };