|
| 1 | +<?php |
| 2 | + |
| 3 | +declare(strict_types=1); |
| 4 | + |
| 5 | +/* |
| 6 | + * This file has been auto generated by Jane, |
| 7 | + * |
| 8 | + * Do no edit it directly. |
| 9 | + */ |
| 10 | + |
| 11 | +namespace Docker\API\Endpoint; |
| 12 | + |
| 13 | +class ContainerAttach extends \Jane\OpenApiRuntime\Client\BaseEndpoint implements \Jane\OpenApiRuntime\Client\AmpArtaxEndpoint, \Jane\OpenApiRuntime\Client\Psr7HttplugEndpoint |
| 14 | +{ |
| 15 | + protected $id; |
| 16 | + |
| 17 | + /** |
| 18 | + * Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached. |
| 19 | +
|
| 20 | + Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything. |
| 21 | +
|
| 22 | + See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details. |
| 23 | +
|
| 24 | + ### Hijacking |
| 25 | +
|
| 26 | + This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket. |
| 27 | +
|
| 28 | + This is the response from the daemon for an attach request: |
| 29 | +
|
| 30 | + ``` |
| 31 | + HTTP/1.1 200 OK |
| 32 | + Content-Type: application/vnd.docker.raw-stream |
| 33 | +
|
| 34 | + [STREAM] |
| 35 | + ``` |
| 36 | +
|
| 37 | + After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server. |
| 38 | +
|
| 39 | + To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers. |
| 40 | +
|
| 41 | + For example, the client sends this request to upgrade the connection: |
| 42 | +
|
| 43 | + ``` |
| 44 | + POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1 |
| 45 | + Upgrade: tcp |
| 46 | + Connection: Upgrade |
| 47 | + ``` |
| 48 | +
|
| 49 | + The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream: |
| 50 | +
|
| 51 | + ``` |
| 52 | + HTTP/1.1 101 UPGRADED |
| 53 | + Content-Type: application/vnd.docker.raw-stream |
| 54 | + Connection: Upgrade |
| 55 | + Upgrade: tcp |
| 56 | +
|
| 57 | + [STREAM] |
| 58 | + ``` |
| 59 | +
|
| 60 | + ### Stream format |
| 61 | +
|
| 62 | + When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload. |
| 63 | +
|
| 64 | + The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`). |
| 65 | +
|
| 66 | + It is encoded on the first eight bytes like this: |
| 67 | +
|
| 68 | + ```go |
| 69 | + header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} |
| 70 | + ``` |
| 71 | +
|
| 72 | + `STREAM_TYPE` can be: |
| 73 | +
|
| 74 | + - 0: `stdin` (is written on `stdout`) |
| 75 | + - 1: `stdout` |
| 76 | + - 2: `stderr` |
| 77 | +
|
| 78 | + `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian. |
| 79 | +
|
| 80 | + Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`. |
| 81 | +
|
| 82 | + The simplest way to implement this protocol is the following: |
| 83 | +
|
| 84 | + 1. Read 8 bytes. |
| 85 | + 2. Choose `stdout` or `stderr` depending on the first byte. |
| 86 | + 3. Extract the frame size from the last four bytes. |
| 87 | + 4. Read the extracted size and output it on the correct output. |
| 88 | + 5. Goto 1. |
| 89 | +
|
| 90 | + ### Stream format when using a TTY |
| 91 | +
|
| 92 | + When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`. |
| 93 | +
|
| 94 | + * |
| 95 | + * @param string $id ID or name of the container |
| 96 | + * @param array $queryParameters { |
| 97 | + * |
| 98 | + * @var string $detachKeys Override the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| 99 | + * @var bool $logs replay previous logs from the container |
| 100 | +
|
| 101 | + * @var bool $stream Stream attached streams from the the time the request was made onwards |
| 102 | + * @var bool $stdin Attach to `stdin` |
| 103 | + * @var bool $stdout Attach to `stdout` |
| 104 | + * @var bool $stderr Attach to `stderr` |
| 105 | + * } |
| 106 | + */ |
| 107 | + public function __construct(string $id, array $queryParameters = []) |
| 108 | + { |
| 109 | + $this->id = $id; |
| 110 | + $this->queryParameters = $queryParameters; |
| 111 | + } |
| 112 | + |
| 113 | + use \Jane\OpenApiRuntime\Client\AmpArtaxEndpointTrait, \Jane\OpenApiRuntime\Client\Psr7HttplugEndpointTrait; |
| 114 | + |
| 115 | + public function getMethod(): string |
| 116 | + { |
| 117 | + return 'POST'; |
| 118 | + } |
| 119 | + |
| 120 | + public function getUri(): string |
| 121 | + { |
| 122 | + return str_replace(['{id}'], [$this->id], '/containers/{id}/attach'); |
| 123 | + } |
| 124 | + |
| 125 | + public function getBody(\Symfony\Component\Serializer\SerializerInterface $serializer, \Http\Message\StreamFactory $streamFactory = null): array |
| 126 | + { |
| 127 | + return [[], null]; |
| 128 | + } |
| 129 | + |
| 130 | + public function getExtraHeaders(): array |
| 131 | + { |
| 132 | + return ['Accept' => ['application/json']]; |
| 133 | + } |
| 134 | + |
| 135 | + protected function getQueryOptionsResolver(): \Symfony\Component\OptionsResolver\OptionsResolver |
| 136 | + { |
| 137 | + $optionsResolver = parent::getQueryOptionsResolver(); |
| 138 | + $optionsResolver->setDefined(['detachKeys', 'logs', 'stream', 'stdin', 'stdout', 'stderr']); |
| 139 | + $optionsResolver->setRequired([]); |
| 140 | + $optionsResolver->setDefaults(['logs' => false, 'stream' => false, 'stdin' => false, 'stdout' => false, 'stderr' => false]); |
| 141 | + $optionsResolver->setAllowedTypes('detachKeys', ['string']); |
| 142 | + $optionsResolver->setAllowedTypes('logs', ['bool']); |
| 143 | + $optionsResolver->setAllowedTypes('stream', ['bool']); |
| 144 | + $optionsResolver->setAllowedTypes('stdin', ['bool']); |
| 145 | + $optionsResolver->setAllowedTypes('stdout', ['bool']); |
| 146 | + $optionsResolver->setAllowedTypes('stderr', ['bool']); |
| 147 | + |
| 148 | + return $optionsResolver; |
| 149 | + } |
| 150 | + |
| 151 | + /** |
| 152 | + * {@inheritdoc} |
| 153 | + * |
| 154 | + * @throws \Docker\API\Exception\ContainerAttachBadRequestException |
| 155 | + * @throws \Docker\API\Exception\ContainerAttachNotFoundException |
| 156 | + * @throws \Docker\API\Exception\ContainerAttachInternalServerErrorException |
| 157 | + */ |
| 158 | + protected function transformResponseBody(string $body, int $status, \Symfony\Component\Serializer\SerializerInterface $serializer) |
| 159 | + { |
| 160 | + if (101 === $status) { |
| 161 | + return null; |
| 162 | + } |
| 163 | + if (200 === $status) { |
| 164 | + return null; |
| 165 | + } |
| 166 | + if (400 === $status) { |
| 167 | + throw new \Docker\API\Exception\ContainerAttachBadRequestException($serializer->deserialize($body, 'Docker\\API\\Model\\ErrorResponse', 'json')); |
| 168 | + } |
| 169 | + if (404 === $status) { |
| 170 | + throw new \Docker\API\Exception\ContainerAttachNotFoundException($serializer->deserialize($body, 'Docker\\API\\Model\\ErrorResponse', 'json')); |
| 171 | + } |
| 172 | + if (500 === $status) { |
| 173 | + throw new \Docker\API\Exception\ContainerAttachInternalServerErrorException($serializer->deserialize($body, 'Docker\\API\\Model\\ErrorResponse', 'json')); |
| 174 | + } |
| 175 | + } |
| 176 | +} |
0 commit comments