Merge pull request #21 from xp-forge/feature/run-local

Implement `xp lambda run [Handler]` to run lambdas locally

Author: thekid

README.md

@@ -38,14 +38,25 @@ If you need to run any initialization code, you can do before returning the lamb
 
 Development
 -----------
-To test your lambda locally, run the following:
+To run your lambda locally, use the following:
+
+```bash
+$ xp lambda run Greet '{"name":"Timm"}'
+Hello Timm from PHP 8.2.7 via Greet @ test-local-1
+```
+
+*This does not provide a complete lambda environment, and does not have any execution limits imposed on it!*
+
+Integration testing
+-------------------
+To test your lambda inside a local containerized lambda environment, use the *test* command.
 
 ```bash
 $ xp lambda test Greet '{"name":"Timm"}'
 START RequestId: 9ff45cda-df9b-1b8c-c21b-5fe27c8f2d24 Version: $LATEST
 END RequestId: 9ff45cda-df9b-1b8c-c21b-5fe27c8f2d24
 REPORT RequestId: 9ff45cda-df9b-1b8c-c21b-5fe27c8f2d24  Init Duration: 922.19 ms...
-"Hello Timm from PHP 8.0.10 via test @ us-east-1"
+"Hello Timm from PHP 8.2.7 via test @ us-east-1"
 ```
 
 *This functionality is provided by the [AWS Lambda base images for custom runtimes](https://gallery.ecr.aws/lambda/provided)*

src/main/php/com/amazon/aws/lambda/Environment.class.php

@@ -38,6 +38,11 @@ public function tempDir(): Path {
     return new Path(sys_get_temp_dir());
   }
 
+  /** Returns whether this is a local invocation */
+  public function local(): bool {
+    return isset($this->variables['AWS_LOCAL']);
+  }
+
   /**
    * Returns a given environment variable
    *

src/main/php/xp/lambda/RunLambda.class.php

@@ -0,0 +1,68 @@
+<?php namespace xp\lambda;
+
+use com\amazon\aws\lambda\{Environment, Context};
+use lang\{XPClass, Throwable};
+use util\UUID;
+use util\cmd\Console;
+
+/**
+ * Run lambdas locally
+ *
+ * @see https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtime-environment.html
+ * @see https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html
+ */
+class RunLambda {
+  const TRACE= 'Root=1-5bef4de7-ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1';
+  const REGION= 'test-local-1';
+
+  private $impl, $events;
+
+  /**
+   * Creates a new `run` subcommand
+   *
+   * @param  string $handler
+   * @param  string... $events
+   * @throws lang.ClassLoadingException
+   */
+  public function __construct($handler= 'Handler', ... $events) {
+    $this->impl= XPClass::forName($handler);
+    $this->events= $events ?: ['{}'];
+  }
+
+  /** Runs this command */
+  public function run(): int {
+    $name= $this->impl->getSimpleName();
+    $region= getenv('AWS_REGION') ?: self::REGION;
+    $functionArn= "arn:aws:lambda:{$region}:123456789012:function:{$name}";
+    $deadlineMs= (time() + 900) * 1000;
+    $environment= $_ENV + ['AWS_LAMBDA_FUNCTION_NAME' => $name, 'AWS_REGION' => $region, 'AWS_LOCAL' => true];
+
+    try {
+      $target= $this->impl->newInstance(new Environment(getcwd(), Console::$out, $environment))->target();
+      $lambda= $target instanceof Lambda ? [$target, 'process'] : $target;
+    } catch (Throwable $e) {
+      Console::$err->writeLine($e);
+      return 127;
+    }
+
+    $status= 0;
+    foreach ($this->events as $event) {
+      $headers= [
+        'Lambda-Runtime-Aws-Request-Id'       => [UUID::randomUUID()->hashCode()],
+        'Lambda-Runtime-Invoked-Function-Arn' => [$functionArn],
+        'Lambda-Runtime-Trace-Id'             => [self::TRACE],
+        'Lambda-Runtime-Deadline-Ms'          => [$deadlineMs],
+        'Content-Length'                      => [strlen($event)],
+      ];
+
+      try {
+        $result= $lambda(json_decode($event, true), new Context($headers, $environment));
+        Console::$out->writeLine($result);
+      } catch (Throwable $e) {
+        Console::$err->writeLine($e);
+        $status= 1;
+      }
+    }
+    return $status;
+  }
+}

src/main/php/xp/lambda/Runner.class.php

@@ -8,35 +8,39 @@
  * XP AWS Lambda
  * =============
  *
- * - Store runtime layer as `runtime-X.X.X.zip`, building if necessary:
+ * - Run lambda locally:
  *   ```sh
- *   $ xp lambda runtime
+ *   $ xp lambda run Greet '{"name":"Test"}'
  *   ```
- * - Rebuild runtime:
+ * - Package single file in `function.zip` file for deployment:
  *   ```sh
- *   $ xp lambda runtime -b
+ *   $ xp lambda package Greet.class.php
  *   ```
- * - Speficy runtime version, selecting newest PHP 8.0 release:
+ * - Package INI file and source directory in `function.zip`:
  *   ```sh
- *   $ xp lambda runtime:8.0
+ *   $ xp lambda package task.ini src/main/php
  *   ```
- * - Test lambda:
+ * - Test lambda inside a containerized AWS environment:
  *   ```sh
  *   $ xp lambda test Greet '{"name":"Test"}'
  *   ```
  * - Test lambda, pass environment variables:
  *   ```sh
  *   $ xp lambda test -e PROFILE=prod Audit
  *   ```
- * - Package single file in `function.zip` file for deployment:
+ * - Store runtime layer as `runtime-X.X.X.zip`, building if necessary:
  *   ```sh
- *   $ xp lambda package Greet.class.php
+ *   $ xp lambda runtime
  *   ```
- * - Package INI file and source directory in `function.zip`:
+ * - Rebuild runtime:
  *   ```sh
- *   $ xp lambda package task.ini src/main/php
+ *   $ xp lambda runtime -b
+ *   ```
+ * - Speficy runtime version, selecting newest PHP 8.0 release:
+ *   ```sh
+ *   $ xp lambda runtime:8.0
  *   ```
- * The `runtime` and `test` commands require Docker or Podman to be installed!
+ * The `test` and `runtime` commands require Docker or Podman to be installed!
  * Packaging will always include the `vendor` directory automatically.
  */
 class Runner {
@@ -66,6 +70,7 @@ private static function command(string $name, array $args): object {
     sscanf($name, "%[^:]:%[^\r]", $command, $version);
     switch ($command) {
       case 'package': return new PackageLambda(new Path('function.zip'), new Sources(new Path('.'), [...$args, 'vendor']));
+      case 'run': return new RunLambda(...$args);
       case 'runtime': return new CreateRuntime(self::resolve($version), new Path('runtime-%s.zip'), in_array('-b', $args));
       case 'test': return new TestLambda(self::resolve($version), new Path('.'), $args);
       default: return new DisplayError('Unknown command "'.$args[0].'"');

src/test/php/com/amazon/aws/lambda/unittest/EnvironmentTest.class.php

@@ -46,6 +46,16 @@ public function non_existant_variable() {
     Assert::null((new Environment('.', null, []))->variable('TEST'));
   }
 
+  #[Test]
+  public function not_local_by_default() {
+    Assert::false((new Environment('.', null, []))->local());
+  }
+
+  #[Test]
+  public function local() {
+    Assert::true((new Environment('.', null, ['AWS_LOCAL' => true]))->local());
+  }
+
   #[Test]
   public function credentials() {
     $env= [