This file contains more in depth information about interacting with the SDK (a.k.a. chroot) in the Build API. The SDK tutorial provides a quick walk-through of the steps to set up an endpoint that runs inside the SDK, and is the recommended starting point if you're just getting started.
The “Path” messages generally refers to three different messages that are used to inject and extract artifacts; Path, ResultPath, and SyncedDir. All three messages can be found in common.proto.
Path and ResultPath MessagesAt its core, Path message simply represents a path on the filesystem inside or outside of the SDK. The message has a path string field for the path itself, which should generally be an absolute path. It also has a location field to note whether the path is inside or outside of the SDK. When constructing a request the location will virtually always be outside, and when constructing a response the location will virtually always be inside. There are plans to make location optional in the long term except in very specific edge cases, but it is currently required.
The ResultPath message is simply a named wrapper around a Path message to allow easily identifying it when used. There may be at most one ResultPath message per request. A ResultPath message in a response is essentially meaningless. A ResultPath field never needs to be used directly in an endpoint, it is only for the Build API itself; instead, the endpoint can produce (or simply locate) the files however is most convenient and put those paths in the response, and they will still end up in the final result path.
There are two use cases for these messages. Files/directories in Path messages in a request are automatically injected into the SDK. Files/directories in Path messages in a response are automatically extracted from the SDK when there is a ResultPath message in the request.
Injection is accomplished by simply setting a Path message in a request to the file or directory that is to be injected. The files/directories are copied into a /tmp directory in the SDK. Each Path gets a separate /tmp directory to avoid collisions. When given a directory, the contents will be copied recursively. This injection process is handled entirely by the Build API itself. The endpoint itself will only ever see the injected path, and does not need to worry about the outside path, or cleaning up the file.
The following examples provide the populated request values outside the SDK, as well as the request values inside the SDK, which is what the endpoint would actually see.
Example 1: Single file.
Path = ~/input/file.txtPath = /tmp/tmp-abc123/file.txtExample 2: Single directory.
Path = ~/inputPath = /tmp/tmp-abc123Example 3: Multiple paths.
Path = ~/inputPath = ~/file1.txtPath = ~/file2.txtPath = /tmp/tmp-abc123Path = /tmp/tmp-xyz789/file1.txtPath = /tmp/tmp-123456/file2.txtThe two components to extraction are a ResultPath field in the request, and one or more Path fields in the response. The ResultPath specifies the path outside the SDK where the artifact(s) should be extracted to. The Path fields specify one or more files and/or directories inside the SDK that should be extracted. The artifacts inside the SDK do not need to be collected prior to extraction, however, non-unique names will cause undefined behavior.
In practice, that currently means files will be overwritten, and directories will raise an error. The behavior of non-unique names may change at any time, and in the future we may define the behavior as something other than what it is today, so until such a time, ensure you have unique paths to guarantee it works properly. See examples 5 and 6 for possible collision outputs today.
Example 1: Multiple unique files.
ResultPath = ~/resultsPath file1 = /inside/file1Path file2 = /other/inside/file2Example 2: Multiple directories.
ResultPath = ~/resultsPath dir1 = /inside/dir1Path dir2 = /other/inside/dir2Example 3: Nested directories.
ResultPath = ~/resultsPath dir1 = /inside/dirPath dir2 = /other/inside/dirExample 4: File and directory.
ResultPath = ~/resultsPath file = /inside/filePath dir = /inside/dirExample 5: (Undefined Behavior) File name collision!
ResultPath = ~/resultsPath file1 = /inside/file = ‘File content!’Path file2 = /other/inside/file = ‘Different content!’Example 6: (Undefined Behavior) File collisions in nested directories.
ResultPath = ~/resultsPath dir1 = /inside/dir1Path dir2 = /other/inside/dir2SyncedDir MessageA SyncedDir must be in a request to use the functionality. The SyncedDir provides a means of syncing the contents of a directory into and out of the SDK. Everything inside the directory in injected into the SDK just like a directory in a Path field would be. The key difference is that the contents of the directory are also extracted from the SDK after the endpoint completes. This is a destructive operation, it will remove files that were in the directory if they were deleted from the folder inside the SDK.
SyncedDir = ~/syncedSyncedDir = /tmp/tmp-abc123SyncedDir = /tmp/tmp-abc123