Skip to content

[RFC] Consider adding functional API #330

Closed

Description

@clue

Our OOP API has a pretty good, SOLID design – but let's face it, this often makes it hard to work with. For example, take a look at the following code required to connect to a remote host:

$loop = React\EventLoop\Factory::create();
$resolverFactory = new React\Dns\Resolver\Factory();
$resolver = $resolverFactory->create('8.8.8.8', $loop);
$connector = new Connector($loop, $resolver);
$secure = new SecureConnector($connector, $loop);

$secure->create('www.google.com', 443);

Our current OOP API suffers from the fact that we do not require any global/shared state. This means we can not assume any defaults for common setups and requires passing quite a few instances. Instances that are effectively only constructed once.

After discussing this with @cboden, I figured it's worth opening this ticket as a basis for further discussion / RFC:

This ticket suggests we add a much simpler API on top of the existing class hierarchy (and does not suggest replacing it!). So we're merely talking about some API sugar.

Note however, this comes at the cost of some global state.

At the lowest level, we need a global accessor for the current loop (this has originally been suggested by @igorw (reactphp/event-loop#10)):

$loop = \React\EventLoop\loop();

Stream component (requires global loop):

\React\Stream\fopen('demo.txt', 'r')->then(function (Stream $stream) {

});

DNS component (requires global loop and DNS Resolver):

\React\Dns\lookup('www.google.com')->then(function ($ip) {
    echo $ip;
});

SocketClient component (requires global loop and DNS Resolver):

\React\SocketClient\connect('google.com:80')->then(function (Connection $connection) {

});

Socket component (requires global loop):

\React\Socket\listen('localhost:1234')->then(function (Socket $socket) {
    $socket->on('connection', function () { });
});

Activity

  1. changed the title [-]Consider adding functional API[/-] [+][RFC] Consider adding functional API[/+] on Jul 6, 2016
  2. clue commented on Jul 6, 2016

    @clue
    MemberAuthor

    This ticket aims to spark the discussion – it does not necessarily suggest we actually implement this.

    Given there's very little interest in this, I'm not sure this is very persuading :)

    I'd like to make this actionable so we can close this, does anybody have any feedback?

  3. WyriHaximus commented on Jul 6, 2016

    @WyriHaximus
    Member

    The global state of things ties in nicely with the work done at https://github.com/async-interop/event-loop Personally I like this approach and provides an quicker to use API

  4. SamMousa commented on Aug 19, 2016

    @SamMousa

    I think currently we have this for the TCP connector.

  5. clue commented on Aug 19, 2016

    @clue
    MemberAuthor

    I think currently we have this for the TCP connector.

    I'm not sure I follow, perhaps you care to elaborate? :-) Who is "we", what is "this" and the "TCP connector"? :-)

  6. SamMousa commented on Aug 19, 2016

    @SamMousa

    https://github.com/reactphp/socket-client/blob/master/src/TcpConnector.php

    We as in the reactphp project / github account / the community :p

  7. clue commented on Aug 19, 2016

    @clue
    MemberAuthor

    I'm not sure we're talking about the same thing here :-)

    This ticket aims to discuss the possibility of introducing global state and a functional API to match, i.e. based on plain functions instead of OOP methods. Most of React's current APIs are based on OOP methods which make extensive use of DI for their various dependencies.

    The TcpConnector has been introduced with SocketClient v0.5.0 and provides very limited functionality. It thus skips the step of requiring a Resolver instance, however it still depends on the LoopInterface. The current API can be used liks this:

    $loop = React\EventLoop\Factory::create();
    $connector = new TcpConnector($loop);
    
    $promise = $connector->create('127.0.0.1', 80);

    While the envisioned API could looks something like this:

    $promise = React\SocketClient\connect('127.0.0.1:80');

    While these may look similar, this becomes much more apparent when trying to establish a TLS connection instead. As discussed above, the first example now requires a total of 6 classes like this:

    $loop = React\EventLoop\Factory::create();
    $resolverFactory = new React\Dns\Resolver\Factory();
    $resolver = $resolverFactory->create('8.8.8.8', $loop);
    $connector = new TcpConnector($loop);
    $dnsConnector = new DnsConnector($connector, $resolver);
    $secure = new SecureConnector($dnsConnector, $loop);
    
    $promise = $secure->create('www.google.com', 443);

    While the functional API would still look exactly the same:

    $promise = React\SocketClient\connect('tls://www.google.com:443');
  8. SamMousa commented on Aug 19, 2016

    @SamMousa

    Ah, then I misunderstood; thought you were talking about an api that uses
    promises to allow for the easy chaining via ->then().

    On Aug 19, 2016 2:28 PM, "Christian Lück" notifications@github.com wrote:

    I'm not sure we're talking about the same thing here :-)

    This ticket aims to discuss the possibility of introducing global state
    and a functional API to match, i.e. based on plain functions instead of OOP
    methods. Most of React's current APIs are based on OOP methods which make
    extensive use of DI for their various dependencies.

    The TcpConnector has been introduced with SocketClient v0.5.0 and
    provides very limited functionality. It thus skips the step of requiring a
    Resolver instance, however it still depends on the LoopInterface. The
    current API can be used liks this:

    $loop = React\EventLoop\Factory::create();$connector = new TcpConnector($loop);$promise = $connector->create('127.0.0.1', 80);

    While the envisioned API could looks something like this:

    $promise = React\SocketClient\connect('127.0.0.1:80');

    While these may look similar, this becomes much more apparent when trying
    to establish a TLS connection instead. As discussed above, the first
    example now requires a total of 6 classes like this:

    $loop = React\EventLoop\Factory::create();$resolverFactory = new React\Dns\Resolver\Factory();$resolver = $resolverFactory->create('8.8.8.8', $loop);$connector = new TcpConnector($loop);$dnsConnector = new DnsConnector($connector, $resolver);$secure = new SecureConnector($dnsConnector, $loop);$promise = $secure->create('www.google.com', 443);

    While the functional API would still look exactly the same:

    $promise = React\SocketClient\connect('tls://www.google.com:443');

    —
    You are receiving this because you commented.
    Reply to this email directly, view it on GitHub
    #330 (comment), or mute
    the thread
    https://github.com/notifications/unsubscribe-auth/AAhYzVv1r9ZFfgyUqrSZVaO7rv40T1MSks5qhaFvgaJpZM4E60Us
    .

  9. WyriHaximus commented on Feb 22, 2017

    @WyriHaximus
    Member
    $promise = React\SocketClient\connect('tls://www.google.com:443');

    This ^ so much, lets me that happen. (Assuming @reactphp/core agree.)

  10. idimensionz commented on Sep 10, 2017

    @idimensionz

    Could a dependency injection engine/component help with this? For example, Symfony's DI component allow dependencies to be injected as defined in a config file. (Note that even in a Docker environment, the config file could be customized based on docker parameters.) See https://symfony.com/doc/current/components/dependency_injection.html for info on Symfony's DI component (info on config files near the bottom).

  11. clue commented on Oct 17, 2017

    @clue
    MemberAuthor

    I still think that this feature may make sense for some use cases 👍 However, there are currently no immediate plans to build this from my end (no demand at the moment and more important outstanding issues currently), but I would be really happy to accept PRs 👍

    Nowadays, the APIs are much more stable than when this issue was originally created and most components assume sane defaults for optional parameters.

    If anybody else feels like picking this up, I suppose we're happy to accepts PRs and reconsider this 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions