Merge pull request #48 from clue-labs/archive

Add `containerArchive()` and `containerArchiveStream()` methods and deprecate `containerCopy()` and `containerCopyStream()`
clue · Sep 7, 2019 · 5a1b473 · 5a1b473
2 parents 9718e6a + e7449f7
commit 5a1b473
Show file tree

Hide file tree

Showing 3 changed files with 102 additions and 8 deletions.
diff --git a/examples/copy.php → examples/archive.php b/examples/copy.php → examples/archive.php
@@ -1,5 +1,5 @@
 <?php
-// this example shows how the containerCopy() call returns a TAR stream,
+// this example shows how the containerArchiveStream() method returns a TAR stream,
 // how it can be passed to a TAR decoder and how we can then pipe each
 // individual file to the console output.
 
@@ -20,7 +20,7 @@
 $factory = new Factory($loop);
 $client = $factory->createClient();
 
-$stream = $client->containerCopyStream($container, $path);
+$stream = $client->containerArchiveStream($container, $path);
 
 $tar = new Decoder();
 

diff --git a/src/Client.php b/src/Client.php
@@ -557,7 +557,7 @@ public function containerRemove($container, $v = false, $force = false)
     }
 
     /**
-     * Copy files or folders of container id
+     * [deprecated] Copy files or folders of container id
      *
      * This resolves with a string in the TAR file format containing all files
      * specified in the given $path.
@@ -575,6 +575,8 @@ public function containerRemove($container, $v = false, $force = false)
      * @return PromiseInterface Promise<string> tar stream
      * @link https://docs.docker.com/engine/api/v1.22/#copy-files-or-folders-from-a-container
      * @link https://github.com/clue/reactphp-tar
+     * @deprecated 0.3.0 Deprecated in Docker Engine API v1.20 (Docker v1.8) and removed in Docker Engine API v1.24 (Docker v1.12), use `containerArchive()` instead
+     * @see self::containerArchive()
      * @see self::containerCopyStream()
      */
     public function containerCopy($container, $path)
@@ -593,7 +595,7 @@ public function containerCopy($container, $path)
     }
 
     /**
-     * Copy files or folders of container id
+     * [Deprecated] Copy files or folders of container id
      *
      * This returns a stream in the TAR file format containing all files
      * specified in the given $path.
@@ -613,6 +615,8 @@ public function containerCopy($container, $path)
      * @return ReadableStreamInterface tar stream
      * @link https://docs.docker.com/engine/api/v1.22/#copy-files-or-folders-from-a-container
      * @link https://github.com/clue/reactphp-tar
+     * @deprecated 0.3.0 Deprecated in Docker Engine API v1.20 (Docker v1.8) and removed in Docker Engine API v1.24 (Docker v1.12), use `containerArchiveStream()` instead
+     * @see self::containerArchiveStream()
      * @see self::containerCopy()
      */
     public function containerCopyStream($container, $path)
@@ -635,6 +639,80 @@ public function containerCopyStream($container, $path)
         );
     }
 
+    /**
+     * Get a tar archive of a resource in the filesystem of container id.
+     *
+     * This resolves with a string in the TAR file format containing all files
+     * specified in the given $path.
+     *
+     * Keep in mind that this means the whole string has to be kept in memory.
+     * For bigger containers it's usually a better idea to use a streaming approach,
+     * see containerArchiveStream() for more details.
+     *
+     * Accessing individual files in the TAR file format string is out of scope
+     * for this library. Several libraries are available, one that is known to
+     * work is clue/reactphp-tar (see links).
+     *
+     * @param string $container container ID
+     * @param string $resource  path to file or directory to archive
+     * @return PromiseInterface Promise<string> tar stream
+     * @link https://docs.docker.com/engine/api/v1.40/#operation/ContainerArchive
+     * @link https://github.com/clue/reactphp-tar
+     * @since 0.3.0 Available as of Docker Engine API v1.20 (Docker v1.8), use deprecated `containerCopy()` on legacy versions
+     * @see self::containerArchiveStream()
+     */
+    public function containerArchive($container, $path)
+    {
+        return $this->browser->get(
+            $this->uri->expand(
+                '/containers/{container}/archive{?path}',
+                array(
+                    'container' => $container,
+                    'path' => $path
+                )
+            )
+        )->then(array($this->parser, 'expectPlain'));
+    }
+
+    /**
+     * Get a tar archive of a resource in the filesystem of container id.
+     *
+     * This returns a stream in the TAR file format containing all files
+     * specified in the given $path.
+     *
+     * This works for (any number of) files of arbitrary sizes as only small chunks have to
+     * be kept in memory.
+     *
+     * Accessing individual files in the TAR file format stream is out of scope
+     * for this library. Several libraries are available, one that is known to
+     * work is clue/reactphp-tar (see links).
+     *
+     * The resulting stream is a well-behaving readable stream that will emit
+     * the normal stream events.
+     *
+     * @param string $container container ID
+     * @param string $path      path to file or directory to archive
+     * @return ReadableStreamInterface tar stream
+     * @link https://docs.docker.com/engine/api/v1.40/#operation/ContainerArchive
+     * @link https://github.com/clue/reactphp-tar
+     * @since 0.3.0 Available as of Docker Engine API v1.20 (Docker v1.8), use deprecated `containerCopyStream()` on legacy versions
+     * @see self::containerArchive()
+     */
+    public function containerArchiveStream($container, $path)
+    {
+        return $this->streamingParser->parsePlainStream(
+            $this->browser->withOptions(array('streaming' => true))->get(
+                $this->uri->expand(
+                    '/containers/{container}/archive{?path}',
+                    array(
+                        'container' => $container,
+                        'path' => $path
+                    )
+                )
+            )
+        );
+    }
+
     /**
      * List images
      *

diff --git a/tests/ClientTest.php b/tests/ClientTest.php
@@ -244,8 +244,7 @@ public function testContainerCopy()
         $data = 'tar stream';
         $this->expectRequestFlow('post', '/containers/123/copy', $this->createResponse($data), 'expectPlain');
 
-        $config = array('Resource' => 'file.txt');
-        $this->expectPromiseResolveWith($data, $this->client->containerCopy('123', $config));
+        $this->expectPromiseResolveWith($data, $this->client->containerCopy('123', 'file.txt'));
     }
 
     public function testContainerCopyStream()
@@ -255,8 +254,25 @@ public function testContainerCopyStream()
         $this->expectRequest('post', '/containers/123/copy', $this->createResponse(''));
         $this->streamingParser->expects($this->once())->method('parsePlainStream')->will($this->returnValue($stream));
 
-        $config = array('Resource' => 'file.txt');
-        $this->assertSame($stream, $this->client->containerCopyStream('123', $config));
+        $this->assertSame($stream, $this->client->containerCopyStream('123', 'file.txt'));
+    }
+
+    public function testContainerArchive()
+    {
+        $data = 'tar stream';
+        $this->expectRequestFlow('GET', '/containers/123/archive?path=file.txt', $this->createResponse($data), 'expectPlain');
+
+        $this->expectPromiseResolveWith($data, $this->client->containerArchive('123', 'file.txt'));
+    }
+
+    public function testContainerArchiveStream()
+    {
+        $stream = $this->getMockBuilder('React\Stream\ReadableStreamInterface')->getMock();
+
+        $this->expectRequest('GET', '/containers/123/archive?path=file.txt', $this->createResponse(''));
+        $this->streamingParser->expects($this->once())->method('parsePlainStream')->will($this->returnValue($stream));
+
+        $this->assertSame($stream, $this->client->containerArchiveStream('123', 'file.txt'));
     }
 
     public function testImageList()