ng: new sync client interface

Author: jakubkulhan

.travis.yml

@@ -5,9 +5,8 @@ sudo: required
 language: php
 
 php:
-  - 7.0
-  - 7.1
   - 7.2
+  - 7.3
   - nightly
 
 cache:

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2015-2018 Jakub Kulhan <[email protected]>
+Copyright (c) 2015-2019 Jakub Kulhan <[email protected]>
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

composer.json

@@ -25,7 +25,7 @@
         }
     ],
     "require": {
-        "php": "~7.0",
+        "php": "~7.2",
         "psr/log": "~1.0",
         "react/event-loop": "^1.0 || ^0.5 || ^0.4",
         "react/promise": "~2.2"

src/Bunny/NG/ClosableInterface.php

@@ -0,0 +1,23 @@
+<?php
+namespace Bunny\NG;
+
+/**
+ * Resource that must be explicitly closed.
+ *
+ * @author Jakub Kulhan <[email protected]>
+ */
+interface ClosableInterface
+{
+
+    /**
+     * Closes the resource.
+     *
+     * After the resource is closed behavior of any of its method is undefined.
+     *
+     * If the resource is not closed by calling this method, it will trigger an error in its destructor.
+     *
+     * @return void
+     */
+    public function close();
+
+}

src/Bunny/NG/RabbitChannelInterface.php

@@ -0,0 +1,12 @@
+<?php
+namespace Bunny\NG;
+
+/**
+ * Channel on the connection to an AMQP 0.9.1 broker.
+ *
+ * @author Jakub Kulhan <[email protected]>
+ */
+interface RabbitChannelInterface extends ClosableInterface
+{
+    // TODO: channel methods
+}

src/Bunny/NG/RabbitClientInterface.php

@@ -0,0 +1,65 @@
+<?php
+namespace Bunny\NG;
+
+/**
+ * Client manages a single connection for message publications and subscriptions.
+ *
+ * It also serves as a connection factory by its `newConnection` method.
+ *
+ * @author Jakub Kulhan <[email protected]>
+ */
+interface RabbitClientInterface
+{
+
+    /**
+     * Publishes the message on the client-managed connection.
+     *
+     * If the client is not connected, a new connection will be opened.
+     *
+     * If the connection gets broken, an exception will be thrown.
+     *
+     * All publications use the same channel on the connection.
+     *
+     * @param RabbitMessage $message
+     * @return void
+     */
+    public function publish(RabbitMessage $message);
+
+    /**
+     * Consume from one or more queues on the client-managed connection.
+     *
+     * If the client is not connected, a new connection will be opened.
+     *
+     * If the connection gets broken, an exception will be thrown.
+     *
+     * Every subscription gets a new channel. However, all consumers of the subscription share the same channel.
+     *
+     * @param RabbitSubscriptionOptions $options
+     * @param RabbitConsumerOptions[] $consumers
+     * @return RabbitSubscriptionInterface
+     */
+    public function subscribe(RabbitSubscriptionOptions $options, RabbitConsumerOptions ...$consumers): RabbitSubscriptionInterface;
+
+    /**
+     * Send heartbeat on the client-managed connection.
+     *
+     * If the client is not connected, a new connection will be opened.
+     *
+     * This method is supposed to be called either if the application tries to verify that the broker is available,
+     * or it received a message on a subscription and it knows that the heartbeat timeout would be triggered. Otherwise
+     * when the connection waits for new messages, it sends heartbeats automatically.
+     *
+     * @return void
+     */
+    public function ping();
+
+    /**
+     * Opens a new connection with the client's connection options.
+     *
+     * Returned connection is not managed by the client and must be explicitly closed by its `close()` method.
+     *
+     * @return RabbitConnectionInterface
+     */
+    public function newConnection(): RabbitConnectionInterface;
+
+}

src/Bunny/NG/RabbitConnectionInterface.php

@@ -0,0 +1,19 @@
+<?php
+namespace Bunny\NG;
+
+/**
+ * Connection to an AMQP 0.9.1 broker.
+ *
+ * @author Jakub Kulhan <[email protected]>
+ */
+interface RabbitConnectionInterface extends ClosableInterface
+{
+
+    /**
+     * Opens a new channel on the connection.
+     *
+     * @return RabbitChannelInterface
+     */
+    public function newChannel(): RabbitChannelInterface;
+
+}

src/Bunny/NG/RabbitConnectionOptions.php

@@ -0,0 +1,158 @@
+<?php
+namespace Bunny\NG;
+
+use Bunny\NG\Sasl\SaslMechanismInterface;
+
+/**
+ * @author Jakub Kulhan <[email protected]>
+ */
+final class RabbitConnectionOptions
+{
+
+    /**
+     * Hostname or IP address of the server.
+     *
+     * @var string
+     */
+    public $host;
+
+    /**
+     * Server port.
+     *
+     * @var int
+     */
+    public $port;
+
+    /**
+     * Available SASL mechanisms.
+     *
+     * @var SaslMechanismInterface[]
+     */
+    public $mechanisms;
+
+    /**
+     * Server virtual host.
+     *
+     * @var string
+     */
+    public $virtualHost;
+
+    /**
+     * Heartbeat timeout defines max time the connection will be kept idle. Every `heartbeat` seconds the client will send
+     * heartbeat frame to the server. If client doesn't hear from the server in `heartbeat * 2` seconds, the connection
+     * is assumed to be dead.
+     *
+     * @var float
+     */
+    public $heartbeat;
+
+    /**
+     * Timeout to establish the connection (connection parameters tuning, SASL exchange, opening virtual host).
+     *
+     * @var float
+     */
+    public $connectTimeout;
+
+    /**
+     * Parameters for TLS-secured connections.
+     *
+     * @var TlsOptions|null
+     */
+    public $tls;
+
+    public static function new()
+    {
+        return new static();
+    }
+
+    public static function fromUrl(string $url)
+    {
+        throw new \LogicException("TODO");
+    }
+
+    /**
+     * @param string $host
+     * @return self
+     */
+    public function setHost(string $host)
+    {
+        $this->host = $host;
+        return $this;
+    }
+
+    /**
+     * @param int $port
+     * @return self
+     */
+    public function setPort(int $port)
+    {
+        $this->port = $port;
+        return $this;
+    }
+
+    /**
+     * @param SaslMechanismInterface[] $mechanisms
+     * @return self
+     */
+    public function setMechanisms(array $mechanisms)
+    {
+        $this->mechanisms = $mechanisms;
+        return $this;
+    }
+
+    /**
+     * @param SaslMechanismInterface $mechanism
+     * @return self
+     */
+    public function addMechanism(SaslMechanismInterface $mechanism)
+    {
+        if ($this->mechanisms === null) {
+            $this->mechanisms = [];
+        }
+
+        $this->mechanisms[] = $mechanism;
+
+        return $this;
+    }
+
+    /**
+     * @param string $virtualHost
+     * @return self
+     */
+    public function setVirtualHost(string $virtualHost)
+    {
+        $this->virtualHost = $virtualHost;
+        return $this;
+    }
+
+    /**
+     * @param float $heartbeat
+     * @return self
+     */
+    public function setHeartbeat(float $heartbeat)
+    {
+        $this->heartbeat = $heartbeat;
+        return $this;
+    }
+
+    /**
+     * @param float $connectTimeout
+     * @return self
+     */
+    public function setConnectTimeout(float $connectTimeout)
+    {
+        $this->connectTimeout = $connectTimeout;
+        return $this;
+    }
+
+    /**
+     * @param TlsOptions|null $tls
+     * @return self
+     */
+    public function setTLS(?TlsOptions $tls)
+    {
+        $this->tls = $tls;
+        return $this;
+    }
+
+}

src/Bunny/NG/RabbitConsumerOptions.php

@@ -0,0 +1,49 @@
+<?php
+namespace Bunny\NG;
+
+/**
+ * @author Jakub Kulhan <[email protected]>
+ */
+final class RabbitConsumerOptions
+{
+
+    /**
+     * Queue name.
+     *
+     * @var string
+     */
+    public $queue;
+
+    /**
+     * Consumer tag.
+     *
+     * @var string
+     */
+    public $consumerTag;
+
+    public static function new()
+    {
+        return new static();
+    }
+
+    /**
+     * @param string $queue
+     * @return self
+     */
+    public function setQueue(string $queue)
+    {
+        $this->queue = $queue;
+        return $this;
+    }
+
+    /**
+     * @param string $consumerTag
+     * @return self
+     */
+    public function setConsumerTag(string $consumerTag)
+    {
+        $this->consumerTag = $consumerTag;
+        return $this;
+    }
+
+}

src/Bunny/NG/RabbitMessage.php

@@ -0,0 +1,10 @@
+<?php
+namespace Bunny\NG;
+
+/**
+ * @author Jakub Kulhan <[email protected]>
+ */
+final class RabbitMessage
+{
+    // TODO
+}