Merge pull request #36 from jryd/async-events

Add event invocation support

Author: aarondfrancis

docs/functions/executing.md

@@ -37,7 +37,7 @@ exports.handler = async function (event) {
 }
 ```
 
-## Sync vs. Async
+## Sync vs. Async vs. Event
 
 By default, all executions of Sidecar functions are synchronous, meaning script execution will stop while the Lambda finishes and returns its result. This is the simplest method and probably fine for the majority of use cases. 
 
@@ -62,6 +62,20 @@ $result = Sidecar::execute(OgImage::class, $payload = [], $async = true);
 echo 'Image may or may not have finished generating yet!';
 ```
 
+Whilst the execution is asynchronous, it is expected that you wait for the response, which is documented more in the next section below. If you're looking for "fire-and-forget" style execution, where you don't care about the response and are happy for execution to occur in the background then you'll need to execute your function as an event.
+
+```php
+// Event execution using the class. 
+$result = OgImage::executeAsEvent();
+$result = OgImage::execute($payload = [], $async = false, $invocationType = 'Event');
+
+// Event execution using the facade.
+$result = Sidecar::executeAsEvent(OgImage::class);
+$result = Sidecar::execute(OgImage::class, $payload = [], $async = false, $invocationType = 'Event');
+
+echo 'Image may or may not have finished generating yet!';
+```
+
 ### Settled Results
 
 When your function is executed using one of the sync methods, the return value will be an instance of `SettledResult`. The Settled Result class is responsible for delivering the result of your Lambda, along with the logs and information about duration, memory used, etc.
@@ -70,7 +84,7 @@ You can read more about that in the [body](#result-body) and [logs & timing](#lo
 
 ### Pending Results
 
-If you function is invoked using one of the async methods, the return value will be an instance of `PendingResult`. This class is a thin wrapper around a Guzzle promise that represents your pending function execution.
+If your function is invoked using one of the async methods, the return value will be an instance of `PendingResult`. This class is a thin wrapper around a Guzzle promise that represents your pending function execution.
 
 Given a Pending Result, if you'd like to pause execution until the promise is settled, you can call `settled`. This will return a `SettledResult`.
 
@@ -90,6 +104,8 @@ dump($result instanceof SettledResult);
 // true
 ```
 
+Using the async methods is powered by Guzzle promises. Given the limitations of the Guzzle async implementation, as it stands today, you need to wait for the response to ensure all your requests have been made.
+
 ### Working With Either
 
 If you're not sure whether a given result is a Settled Result or a Pending Result, you can _always_ called `settled`.

src/LambdaFunction.php

@@ -22,9 +22,9 @@ abstract class LambdaFunction
      * @param  bool  $async
      * @return SettledResult|PendingResult
      */
-    public static function execute($payload = [], $async = false)
+    public static function execute($payload = [], $async = false, $invocationType = 'RequestResponse')
     {
-        return Sidecar::execute(static::class, $payload, $async);
+        return Sidecar::execute(static::class, $payload, $async, $invocationType);
     }
 
     /**
@@ -65,6 +65,17 @@ public static function executeManyAsync($payloads)
         return static::executeMany($payloads, $async = true);
     }
 
+    /**
+     * Execute the current function asynchronously as an event. This is "fire-and-forget" style.
+     *
+     * @param  array  $payload
+     * @return PendingResult
+     */
+    public static function executeAsEvent($payload = [])
+    {
+        return static::execute($payload, $async = false, $invocationType = 'Event');
+    }
+
     /**
      * Deploy this function only.
      *

src/Manager.php

@@ -62,7 +62,7 @@ public function overrideExecutionVersion($version, $callback = null)
      * @throws Exceptions\SidecarException
      * @throws FunctionNotFoundException
      */
-    public function execute($function, $payload = [], $async = false)
+    public function execute($function, $payload = [], $async = false, $invocationType = 'RequestResponse')
     {
         // Could be a FQCN.
         if (is_string($function)) {
@@ -85,7 +85,7 @@ public function execute($function, $payload = [], $async = false)
                 // `RequestResponse` is a synchronous call, vs `Event` which
                 // is a fire-and-forget, we can make it async by using the
                 // invokeAsync method.
-                'InvocationType' => 'RequestResponse',
+                'InvocationType' => $invocationType,
 
                 // Include the execution log in the response.
                 'LogType' => 'Tail',
@@ -166,6 +166,19 @@ public function executeManyAsync($params)
         return $this->executeMany($params, $async = true);
     }
 
+    /**
+     * @param $function
+     * @param  array  $payload
+     * @return PendingResult|SettledResult
+     *
+     * @throws Exceptions\SidecarException
+     * @throws FunctionNotFoundException
+     */
+    public function executeAsEvent($function, $payload = [])
+    {
+        return $this->execute($function, $payload, $async = false, $invocationType = 'Event');
+    }
+
     /**
      * Get an array of instantiated functions.
      *

tests/Unit/ExecuteTest.php

@@ -195,4 +195,79 @@ public function async_execution_by_facade_with_instantiated_class()
 
         $this->assertEvents();
     }
+
+    /** @test */
+    public function event_invocation_execution_by_function()
+    {
+        $this->mockInvoke([
+            'InvocationType' => 'Event',
+            'Payload' => '{"foo":"bar"}'
+        ]);
+
+        EmptyTestFunction::execute([
+            'foo' => 'bar'
+        ], $async = false, $invocationType = 'Event');
+
+        $this->assertEvents();
+    }
+
+    /** @test */
+    public function event_invocation_execution_by_function_with_event_helper()
+    {
+        $this->mockInvoke([
+            'InvocationType' => 'Event',
+            'Payload' => '{"foo":"bar"}'
+        ]);
+
+        EmptyTestFunction::executeAsEvent([
+            'foo' => 'bar'
+        ]);
+
+        $this->assertEvents();
+    }
+
+    /** @test */
+    public function event_invocation_execution_by_facade()
+    {
+        $this->mockInvoke([
+            'InvocationType' => 'Event',
+            'Payload' => '{"foo":"bar"}'
+        ]);
+
+        Sidecar::execute(EmptyTestFunction::class, [
+            'foo' => 'bar'
+        ], $async = false, $invocationType = 'Event');
+
+        $this->assertEvents();
+    }
+
+    /** @test */
+    public function event_invocation_execution_by_facade_directly()
+    {
+        $this->mockInvoke([
+            'InvocationType' => 'Event',
+            'Payload' => '{"foo":"bar"}'
+        ]);
+
+        Sidecar::executeAsEvent(EmptyTestFunction::class, [
+            'foo' => 'bar'
+        ]);
+
+        $this->assertEvents();
+    }
+
+    /** @test */
+    public function event_invocation_execution_by_facade_with_instantiated_class()
+    {
+        $this->mockInvoke([
+            'InvocationType' => 'Event',
+            'Payload' => '{"foo":"bar"}'
+        ]);
+
+        Sidecar::execute(new EmptyTestFunction, [
+            'foo' => 'bar'
+        ], $async = false, $invocationType = 'Event');
+
+        $this->assertEvents();
+    }
 }