golang.org/x/build@v0.0.0-20240506185731-218518f32b70/doc/remote-buildlet.txt (about)

     1  A remote buildlet is a buildlet created or assigned by the
     2  coordinator, on request of a client (such as cmd/gomote or
     3  cmd/relui). The client must occasionally refresh the buildlet to
     4  keep it alive, and the coordinator proxies all requests to it.
     5  Currently, if the coordinator dies or restarts, all buildlets are lost.
     6  
     7  The permission to do this is controlled by a special type of build key
     8  starting with "user-" instead of a GOOS. The form will be of
     9  "user-USERNAME". The user-$username and key
    10  (via https://build.golang.org/key?builder=user-WHO) are sent via
    11  HTTP Basic authentication.
    12  
    13  Flow:
    14  
    15  *) Client (e.g. pkg buildlet, via cmd/gomote or cmd/relui) makes a
    16     POST request over key-pinned TLS to the well-known TLS cert of
    17     farmer.golang.org
    18  
    19        POST https://farmer.golang.org/buildlet/create HTTP/1.1
    20        Authentication: Basic user-$username userkey
    21        Content-Type: www/form-url-encoded
    22  
    23        type=darwin-amd64
    24  
    25        HTTP/1.1 200 OK
    26        Content-Type: application/json
    27  
    28        {
    29            "Name": "user-adg-darwin-amd64-0",
    30            "Type": "darwin-amd64",
    31            "Created": "..",
    32            "Expires": "..",
    33        }
    34  
    35  *) Client may list open buildlets like:
    36  
    37     GET https://farmer.golang.org/buildlet/list HTTP/1.1
    38     Authentication: Basic user-$username userkey
    39  
    40     HTTP/1.1 200 OK
    41     Content-Type: application/json
    42  
    43     [ {"Name": ...}, {"Name": ...}]
    44  
    45  *) Client makes requests like:
    46  
    47        (buildlet method) https://farmer.golang.org/(normal buildlet paths) HTTP/1.1
    48        X-Buildlet-Proxy: adg-darwin-amd64-1
    49        Authentication: Basic buildlet-$username $buildkey
    50  
    51     If buildlet is missing, 502 Bad Gateway.
    52     If auth is bad, 401.
    53  
    54  *) Client may release it by doing the normal buildlet.Client.Destroy call
    55     to its /halt method.