images::list

Tag 15: a client asks which images it has built on the server; the server sends every such image as added, says when the listing is whole, keeps sending as images are built and deleted, and finishes when the client stops.

A client opens the scope with a request whose payload is the tag byte 15 and nothing more. The server sends every image the client built on it, one response each, then the word that the listing is whole, and keeps the scope open: an image built is sent as added, an image deleted as removed, for as long as the scope lives. The scope ends at the client’s stop, at the client’s connection ending, or at an error; the response finish follows, and no frame follows the finish.

The request. The request carries no parameter; the tag is the whole of it. Request states its form.
The response. Response states the responses and the sequence of the main stream.
The channels. The client opens the one channel of Client Channels, the stop. The server opens no channel on a list scope.
The listing. The listing is zero or more images. The listing contains every image that the client built by an images::build request and has not deleted by an images::delete request, and no other image. Every image in the listing may be named by the client wherever this specification names an image of this family by its name, and may be named by its digest in a container request of the client. An image absent from the listing is one the client cannot name. The Containerfile an image was built from is reported by images::stat, one image at a time.
The client. The client is the identity under which the connection was authorized, as Authorization provides. The listing is that identity’s listing, and contains no image another identity built.
No eviction. The server does not remove an image from the listing on its own account. An image stays listed until the client deletes it.

The order#

The server reads the request. A request whose payload has no byte is not a request of any endpoint, as Endpoints provides.
The server sends the listing. The server sends every image the client built, one response each, the byte 0 followed by the image. A client with no image is sent none.
The server says the listing is whole. The server sends exactly one response whose payload is the byte 2 and nothing else. The server sends it exactly once on a scope, after every response of step 2 and before any other response.
The server keeps the listing. For the life of the scope: when the server has sent the byte 1 of an images::build request by the client, it sends the image built as added; when it has sent the byte 0 of an images::delete request by the client, it sends the image deleted as removed.
The server ends the scope. When the server receives the client’s stop, or the client’s connection ends, the server sends the response finish. When the server cannot list, it sends the byte 4 followed by an error and the response finish.

The rules that hold throughout#

No end of its own. The server does not end the scope because the client has no image, nor because every image listed has been removed. The client’s stop, the client’s connection ending, and an error are the only ends.
Once per name. The server sends an image as added exactly once while it is listed, and as removed exactly once, only after it was sent as added. An image deleted and built again under the same name is sent as removed and then as added. The server sends no image as changed: an image does not change.
An empty listing. The byte 2 with no response before it states that the client has built no image. An empty listing is not an error.
The error. An error states that the server did not list, or could not keep listing, and that nothing is determined about the client’s images from the moment it is sent. Responses sent before the error were sent as the listing stood. An error is not an empty listing.
No image store. A server that holds out no images_store capability keeps no client image and answers every request of this endpoint with exactly one response, the byte 3 alone, and the response finish, before anything is looked up; it sends no image, no byte 2 and serves no channel. Every other requirement of this page holds for a server that holds the capability out.

In this section

Request — The payload is the tag byte 15 alone; the server ignores any bytes that follow the tag.
Response — Responses of the byte 0 or 1 followed by one image in the postcard wire format, added or removed; the byte 2, once, when the listing is whole; the byte 3, alone and first, when the server keeps no client image; or the byte 4 followed by an error as one JSON value, last; and the response finish.
Client Channels — The one channel the client opens on the scope, by tag; the server serves it as its section states and answers a channel request it cannot decode by a channel response finish with nothing before it.