Merge pull request #38 from clue-labs/execstartdetached

Add execStartDetached() API and promote TTY setting instead of config

Author: clue

README.md

@@ -210,7 +210,7 @@ The resulting stream is a well-behaving readable stream that will emit
 the normal stream events:
 
 ```php
-$stream = $client->execStartStream($exec, $config);
+$stream = $client->execStartStream($exec, $tty);
 $stream->on('data', function ($data) {
     // data will be emitted in multiple chunk
     echo $data;

examples/benchmark-exec.php

@@ -24,7 +24,7 @@
 $client = $factory->createClient();
 
 $client->execCreate($container, array('Cmd' => $cmd, 'AttachStdout' => true, 'AttachStderr' => true))->then(function ($info) use ($client) {
-    $stream = $client->execStartStream($info['Id'], array('Tty' => true));
+    $stream = $client->execStartStream($info['Id'], true);
 
     $start = microtime(true);
     $bytes = 0;

examples/exec-inspect.php

@@ -30,7 +30,7 @@
 })->then(function ($info) use ($client) {
     echo 'Inspected after creation: ' . json_encode($info, JSON_PRETTY_PRINT) . PHP_EOL;
 
-    return $client->execStart($info['ID'], array('Tty' => true))->then(function ($out) use ($client, $info) {
+    return $client->execStart($info['ID'], true)->then(function ($out) use ($client, $info) {
         echo 'Starting returned: ';
         var_dump($out);
 

examples/exec-stream.php

@@ -28,7 +28,7 @@
 $out->pause();
 
 $client->execCreate($container, array('Cmd' => $cmd, 'AttachStdout' => true, 'AttachStderr' => true, 'Tty' => true))->then(function ($info) use ($client, $out) {
-    $stream = $client->execStartStream($info['Id'], array('Tty' => true));
+    $stream = $client->execStartStream($info['Id'], true);
     $stream->pipe($out);
 
     $stream->on('error', 'printf');

src/Client.php

@@ -911,23 +911,53 @@ public function execCreate($container, $config)
      * for bigger command outputs, it's usually a better idea to use a streaming
      * approach, see `execStartStream()` for more details.
      *
-     * If detach is true, this API returns after starting the exec command.
-     * Otherwise, this API sets up an interactive session with the exec command.
-     *
-     * @param string $exec   exec ID
-     * @param array  $config (see link)
+     * @param string  $exec exec ID
+     * @param boolean $tty  tty mode
      * @return PromiseInterface Promise<string> buffered exec data
      * @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#exec-start
      * @uses self::execStartStream()
      * @see self::execStartStream()
+     * @see self::execStartDetached()
      */
-    public function execStart($exec, $config = array())
+    public function execStart($exec, $tty = false)
     {
         return $this->streamingParser->bufferedStream(
-            $this->execStartStream($exec, $config)
+            $this->execStartStream($exec, $tty)
         );
     }
 
+    /**
+     * Starts a previously set up exec instance id.
+     *
+     * This resolves after starting the exec command, but without waiting for
+     * the command output (detached mode).
+     *
+     * @param string  $exec exec ID
+     * @param boolean $tty  tty mode
+     * @return PromiseInterface Promise<null>
+     * @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#exec-start
+     * @see self::execStart()
+     * @see self::execStartStream()
+     */
+    public function execStartDetached($exec, $tty = false)
+    {
+        return $this->browser->post(
+            $this->uri->expand(
+                '/exec/{exec}/start',
+                array(
+                    'exec' => $exec
+                )
+            ),
+            array(
+                'Content-Type' => 'application/json'
+            ),
+            $this->json(array(
+                'Detach' => true,
+                'Tty' => !!$tty
+            ))
+        )->then(array($this->parser, 'expectEmpty'));
+    }
+
     /**
      * Starts a previously set up exec instance id.
      *
@@ -938,16 +968,14 @@ public function execStart($exec, $config = array())
      * This works for command output of any size as only small chunks have to
      * be kept in memory.
      *
-     * If detach is true, this API returns after starting the exec command.
-     * Otherwise, this API sets up an interactive session with the exec command.
-     *
-     * @param string $exec   exec ID
-     * @param array  $config (see link)
+     * @param string  $exec exec ID
+     * @param boolean $tty  tty mode
      * @return ReadableStreamInterface stream of exec data
      * @link https://docs.docker.com/reference/api/docker_remote_api_v1.15/#exec-start
      * @see self::execStart()
+     * @see self::execStartDetached()
      */
-    public function execStartStream($exec, $config = array())
+    public function execStartStream($exec, $tty = false)
     {
         return $this->streamingParser->parsePlainStream(
             $this->browser->withOptions(array('streaming' => true))->post(
@@ -960,7 +988,9 @@ public function execStartStream($exec, $config = array())
                 array(
                     'Content-Type' => 'application/json'
                 ),
-                $this->json($config)
+                $this->json(array(
+                    'Tty' => !!$tty
+                ))
             )
         );
     }

tests/ClientTest.php

@@ -385,6 +385,14 @@ public function testExecCreate()
         $this->expectPromiseResolveWith($json, $this->client->execCreate(123, $config));
     }
 
+    public function testExecDetached()
+    {
+        $body = '';
+        $this->expectRequestFlow('POST', '/exec/123/start', $this->createResponse($body), 'expectEmpty');
+
+        $this->expectPromiseResolveWith('', $this->client->execStartDetached(123, true));
+    }
+
     public function testExecStart()
     {
         $data = 'hello world';

tests/FunctionalClientTest.php

@@ -138,7 +138,7 @@ public function testExecInspectBeforeRunning($exec)
      */
     public function testExecStartWhileRunning($exec)
     {
-        $promise = $this->client->execStart($exec, array('Tty' => true));
+        $promise = $this->client->execStart($exec, true);
         $output = Block\await($promise, $this->loop);
 
         $this->assertEquals('hello world', $output);
@@ -175,7 +175,7 @@ public function testExecStreamEmptyOutputWhileRunning($container)
         $this->assertTrue(is_array($exec));
         $this->assertTrue(is_string($exec['Id']));
 
-        $stream = $this->client->execStartStream($exec['Id'], array('Tty' => true));
+        $stream = $this->client->execStartStream($exec['Id'], true);
         $stream->on('end', $this->expectCallableOnce());
 
         $output = Block\await(Stream\buffer($stream), $this->loop);
@@ -187,7 +187,7 @@ public function testExecStreamEmptyOutputWhileRunning($container)
      * @depends testStartRunning
      * @param string $container
      */
-    public function testExecStreamEmptyOutputBecauseOfDetachWhileRunning($container)
+    public function testExecDetachedWhileRunning($container)
     {
         $promise = $this->client->execCreate($container, array(
             'Cmd' => array('sleep', '10'),
@@ -200,10 +200,8 @@ public function testExecStreamEmptyOutputBecauseOfDetachWhileRunning($container)
         $this->assertTrue(is_array($exec));
         $this->assertTrue(is_string($exec['Id']));
 
-        $stream = $this->client->execStartStream($exec['Id'], array('Tty' => true, 'Detach' => true));
-        $stream->on('end', $this->expectCallableOnce());
-
-        $output = Block\await(Stream\buffer($stream), $this->loop);
+        $promise = $this->client->execStartDetached($exec['Id'], true);
+        $output = Block\await($promise, $this->loop);
 
         $this->assertEquals('', $output);
     }