feat: implement interceptors in the runtime library

Signed-off-by: Mark Sagi-Kazar <[email protected]>

Author: sagikazarmark

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;
+}

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;
+    }
+}

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;
+}

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));
+    }
+}