Locking: add comments and expand help text

clicommand/lock_acquire.go

@@ -20,6 +20,12 @@ Description:
    forever) until it can acquire the lock, if the lock is already held by
    another process. If multiple processes are waiting for the same lock, there
    is no ordering guarantee of which one will be given the lock next.
+   
+   To prevent separate processes unlocking each other, the output from ′lock
+   acquire′ should be stored, and passed to ′lock release′.
+   
+   Note that this subcommand is only available when an agent has been started
+   with the ′agent-api′ experiment enabled.
 
 Examples:
 

clicommand/lock_do.go

@@ -20,6 +20,9 @@ Description:
    wait for completion of some shared work, where only one process should do
    the work. 
    
+   Note that this subcommand is only available when an agent has been started
+   with the ′agent-api′ experiment enabled.
+   
    ′lock do′ will do one of two things:
    
    - Print 'do'. The calling process should proceed to do the work and then

clicommand/lock_done.go

@@ -17,6 +17,9 @@ const lockDoneHelpDescription = `Usage:
 Description:
    Completes a do-once lock. This should only be used by the process performing
    the work.
+   
+   Note that this subcommand is only available when an agent has been started
+   with the ′agent-api′ experiment enabled.
 
 Examples:
 

clicommand/lock_get.go

@@ -12,12 +12,15 @@ import (
 
 const lockGetHelpDescription = `Usage:
 
-    buildkite-agent lock get [key]
+   buildkite-agent lock get [key]
 
 Description:
    Retrieves the value of a lock key. Any key not in use returns an empty 
    string.
    
+   Note that this subcommand is only available when an agent has been started
+   with the ′agent-api′ experiment enabled.
+   
    ′lock get′ is generally only useful for inspecting lock state, as the value
    can change concurrently. To acquire or release a lock, use ′lock acquire′ and
    ′lock release′.

clicommand/lock_release.go

@@ -12,11 +12,16 @@ import (
 
 const lockReleaseHelpDescription = `Usage:
 
-   buildkite-agent lock release [key]
+   buildkite-agent lock release [key] [token]
 
 Description:
    Releases the lock for the given key. This should only be called by the
-   process that acquired the lock.
+   process that acquired the lock. To help prevent different processes unlocking
+   each other unintentionally, the output from ′lock acquire′ is required as the
+   second argument.
+   
+   Note that this subcommand is only available when an agent has been started
+   with the ′agent-api′ experiment enabled.
 
 Examples:
 

lock/lock.go

@@ -55,6 +55,10 @@ func (c *Client) Locker(key string) sync.Locker {
 // token or an error. The token must be passed to Unlock in order to unlock the
 // lock later on.
 func (c *Client) Lock(ctx context.Context, key string) (string, error) {
+	// The token generation only has to avoid making the same token twice to
+	// prevent separate processes unlocking each other.
+	// Using crypto/rand to generate 16 bytes is possibly overkill - it's not a
+	// goal to be cryptographically secure - but ensures the result.
 	otp := make([]byte, 16)
 	if _, err := rand.Read(otp); err != nil {
 		return "", err