Merge pull request #23 from xp-forge/feature/streaming

Implement streaming lambda responses

Author: thekid

README.md

@@ -19,7 +19,7 @@ use com\amazon\aws\lambda\Handler;
 
 class Greet extends Handler {
 
-  /** @return com.amazon.aws.lambda.Lambda|callable */
+  /** @return callable|com.amazon.aws.lambda.Lambda|com.amazon.aws.lambda.Streaming */
   public function target() {
     return fn($event, $context) => sprintf(
       'Hello %s from PHP %s via %s @ %s',
@@ -43,7 +43,7 @@ use com\amazon\aws\lambda\Handler;
 
 class Greet extends Handler {
 
-  /** @return com.amazon.aws.lambda.Lambda|callable */
+  /** @return callable|com.amazon.aws.lambda.Lambda|com.amazon.aws.lambda.Streaming */
   public function target() {
     $default= $this->environment->properties('task')->readString('greet', 'default');
 
@@ -60,7 +60,6 @@ class Greet extends Handler {
 
 The lambda's environment accessible via *$this->environment* is an Environment instance, see [below](https://github.com/xp-forge/lambda#environment).
 
-
 ### Logging
 
 To write output to the lambda's log stream, use *trace()*:
@@ -70,7 +69,7 @@ use com\amazon\aws\lambda\Handler;
 
 class Greet extends Handler {
 
-  /** @return com.amazon.aws.lambda.Lambda|callable */
+  /** @return callable|com.amazon.aws.lambda.Lambda|com.amazon.aws.lambda.Streaming */
   public function target() {
     return function($event, $context) {
       $this->environment->trace('Invoked with ', $event);
@@ -83,6 +82,33 @@ class Greet extends Handler {
 
 Any non-string arguments passed will be converted to string using `util.Objects::stringOf()`. To integrate with [XP logging](https://github.com/xp-framework/logging), pass the environment's writer to the console appender, e.g. by using `$cat= Logging::all()->toConsole($this->environment->writer)`.
 
+### Response streaming
+
+This library supports AWS Lambda response streaming as [announced by AWS in April 2023](https://aws.amazon.com/de/blogs/compute/introducing-aws-lambda-response-streaming/). To use the stream, return a `function(var, Stream, Context)` from the handler's *target()* method instead of a `function(var, Context)`:
+
+```php
+use com\amazon\aws\lambda\{Context, Handler, Stream};
+
+class Streamed extends Handler {
+
+  public function target(): callable {
+    return function($event, Stream $stream, Context $context) {
+      $stream->use('text/plain');
+      $stream->write("[".date('r')."] Hello world...\n");
+
+      sleep(1);
+
+      $stream->write("[".date('r')."] ...from Lambda\n");
+      $stream->end();
+    };
+  }
+}
+```
+
+Invoking this lambda will yield the following:
+
+![Streaming in Terminal](https://github.com/xp-forge/lambda/assets/696742/41785beb-3903-45a0-a2ec-2c7c27c2c7b4)
+
 Development
 -----------
 To run your lambda locally, use the following:
@@ -206,9 +232,9 @@ In order to programmatically use other AWS services use the *ServiceEndpoint* cl
 use com\amazon\aws\{Credentials, ServiceEndpoint};
 use com\amazon\aws\lambda\Handler;
 
-class Streaming extends Handler {
+class WebSockets extends Handler {
 
-  /** @return com.amazon.aws.lambda.Lambda|callable */
+  /** @return callable|com.amazon.aws.lambda.Lambda|com.amazon.aws.lambda.Streaming */
   public function target() {
     return function($event, $context) {
 
@@ -228,7 +254,7 @@ class Streaming extends Handler {
 To test this locally, pass the necessary environment variables via *-e* on the command line:
 
 ```bash
-$ xp lambda test -e AWS_ACCESS_KEY_ID=... -e AWS_SECRET_ACCESS_KEY=... Streaming '{"requestContext":...}'
+$ xp lambda test -e AWS_ACCESS_KEY_ID=... -e AWS_SECRET_ACCESS_KEY=... WebSockets '{"requestContext":...}'
 # ...
 ```
 

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

@@ -1,7 +1,5 @@
 <?php namespace com\amazon\aws\lambda;
 
-use lang\IllegalArgumentException;
-
 /**
  * Base class for lambda handlers. Subclasses overwrite the `target` method,
  * perform initialization there and finally return the invokeable lambda.
@@ -19,18 +17,6 @@ public function __construct(Environment $environment) {
   /** @return com.amazon.aws.lambda.Environment */
   public function environment() { return $this->environment; }
 
-  /** @return com.amazon.aws.lambda.Lambda|callable */
+  /** @return com.amazon.aws.lambda.Lambda|com.amazon.aws.lambda.Streaming|callable */
   public abstract function target();
-
-  /** @return callable */
-  public final function lambda() {
-    $target= $this->target();
-    if ($target instanceof Lambda) {
-      return [$target, 'process'];
-    } else if (is_callable($target)) {
-      return $target;
-    } else {
-      throw new IllegalArgumentException('Expected either a callable or a Lambda instance, have '.typeof($target));
-    }
-  }
 }

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

@@ -0,0 +1,32 @@
+<?php namespace com\amazon\aws\lambda;
+
+use lang\Value;
+use util\Comparison;
+
+/** @see https://docs.aws.amazon.com/lambda/latest/dg/runtimes-custom.html#runtimes-custom-response-streaming */
+abstract class InvokeMode implements Value {
+  use Comparison;
+
+  protected $api, $identifier;
+
+  /** Creates a new invoke mode instance */
+  public function __construct(RuntimeApi $api, $identifier) {
+    $this->api= $api;
+    $this->identifier= $identifier;
+  }
+
+  /**
+   * Invokes the given lambda
+   *
+   * @param  callable $lambda
+   * @param  var $event
+   * @param  com.amazon.aws.lambda.Context $context
+   * @return peer.HttpResponse
+   */
+  public abstract function invoke($lambda, $event, $context);
+
+  /** @return string */
+  public function toString() {
+    return strtr(self::class, '\\', '.').'<'.$this->identifier.'>';
+  }
+}

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

@@ -0,0 +1,27 @@
+<?php namespace com\amazon\aws\lambda;
+
+class Invokeable {
+  public $callable, $mode;
+
+  /**
+   * Create a new invokeable
+   *
+   * @param  callable $callable
+   * @param  com.amazon.aws.lambda.InvokeMode $mode
+   */
+  public function __construct($callable, InvokeMode $mode) {
+    $this->callable= $callable;
+    $this->mode= $mode;
+  }
+
+  /**
+   * Invoke this instance
+   *
+   * @param  var $event
+   * @param  com.amazon.aws.lambda.Context $context
+   * @return var
+   */
+  public function invoke($event, Context $context) {
+    return $this->mode->invoke($this->callable, $event, $context);
+  }
+}