From bf1c1cb28095a2915a6f15142dc0fcfe02b0b9d8 Mon Sep 17 00:00:00 2001
From: Mark Sagi-Kazar <mark.sagikazar@gmail.com>
Date: Tue, 2 Nov 2021 18:39:55 +0100
Subject: [PATCH] feat: implement interceptors in the runtime library

Signed-off-by: Mark Sagi-Kazar <mark.sagikazar@gmail.com>
---
 lib/src/Interceptor.php            | 23 +++++++++++++
 lib/src/InterceptorChain.php       | 33 +++++++++++++++++++
 lib/src/Method.php                 | 20 +++++++++++
 lib/tests/InterceptorChainTest.php | 53 ++++++++++++++++++++++++++++++
 4 files changed, 129 insertions(+)
 create mode 100644 lib/src/Interceptor.php
 create mode 100644 lib/src/InterceptorChain.php
 create mode 100644 lib/src/Method.php
 create mode 100644 lib/tests/InterceptorChainTest.php

diff --git a/lib/src/Interceptor.php b/lib/src/Interceptor.php
new file mode 100644
index 0000000..2d6cc0d
--- /dev/null
+++ b/lib/src/Interceptor.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Twirp;
+
+/**
+ * Interceptor is a form of middleware for Twirp requests, that can be installed on both
+ * clients and servers.
+ *
+ * Just like http middleware, interceptors can mutate requests and responses.
+ * This can enable some powerful integrations, but it should be used with much care
+ * because it may result in code that is very hard to debug.
+ */
+interface Interceptor
+{
+    /**
+     * Intercept a request and return an alternate handler (method).
+     *
+     * The returned method can either wrap the original or can be an entirely new one.
+     */
+    public function intercept(Method $method): Method;
+}
diff --git a/lib/src/InterceptorChain.php b/lib/src/InterceptorChain.php
new file mode 100644
index 0000000..bcfa2f9
--- /dev/null
+++ b/lib/src/InterceptorChain.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Twirp;
+
+/**
+ * Chain multiple Interceptors into a single Interceptor.
+ */
+final class InterceptorChain implements Interceptor
+{
+    /**
+     * @var Interceptor[]
+     */
+    private $interceptors = [];
+
+    public function __construct(Interceptor ...$interceptors)
+    {
+        $this->interceptors = $interceptors;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function intercept(Method $method): Method
+    {
+        foreach ($this->interceptors as $interceptor) {
+            $method = $interceptor->intercept($method);
+        }
+
+        return $method;
+    }
+}
diff --git a/lib/src/Method.php b/lib/src/Method.php
new file mode 100644
index 0000000..cc24a5d
--- /dev/null
+++ b/lib/src/Method.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Twirp;
+
+/**
+ * Method is a generic representation of a Twirp-generated RPC method.
+ *
+ * It is used to define Interceptors.
+ */
+interface Method
+{
+    /**
+     * Generic representation of the underlying method call.
+     *
+     * Since PHP doesn't support function types, it is defined as an interface.
+     */
+    public function call(array $ctx, object $request): object;
+}
diff --git a/lib/tests/InterceptorChainTest.php b/lib/tests/InterceptorChainTest.php
new file mode 100644
index 0000000..7580298
--- /dev/null
+++ b/lib/tests/InterceptorChainTest.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Twirp;
+
+use Prophecy\PhpUnit\ProphecyTrait;
+use Prophecy\Prophecy\ObjectProphecy;
+use Twirp\Interceptor;
+use Twirp\InterceptorChain;
+use Twirp\Method;
+
+final class InterceptorChainTest extends \PHPUnit\Framework\TestCase
+{
+    use ProphecyTrait;
+
+    /**
+     * @var InterceptorChain
+     */
+    private $interceptor;
+
+    /**
+     * @var Interceptor|ObjectProphecy
+     */
+    private $interceptor1;
+
+    /**
+     * @var Interceptor|ObjectProphecy
+     */
+    private $interceptor2;
+
+    public function setUp(): void
+    {
+        $this->interceptor1 = $this->prophesize(Interceptor::class);
+        $this->interceptor2 = $this->prophesize(Interceptor::class);
+
+        $this->interceptor = new InterceptorChain($this->interceptor1->reveal(), $this->interceptor2->reveal());
+    }
+
+    /**
+     * @test
+     */
+    public function it_intercepts_a_method(): void
+    {
+        $method1 = $this->prophesize(Method::class)->reveal();
+        $method2 = $this->prophesize(Method::class)->reveal();
+
+        $this->interceptor1->intercept($method1)->willReturn($method2);
+        $this->interceptor2->intercept($method2)->willReturn($method2);
+
+        self::assertSame($method2, $this->interceptor->intercept($method1));
+    }
+}