Add timeout for resource allocation in lock step and freestyle jobs

Adds timeoutForAllocateResource and timeoutUnit parameters to the lock()
pipeline step and lockTimeout/lockTimeoutUnit to freestyle job resource
configuration. When a timeout is set and the resource is not acquired
within the specified duration, the pipeline build fails with a
LockWaitTimeoutException and the freestyle queue item is cancelled.

Implementation uses a single scheduled task targeting the earliest
deadline across all queued entries, with a periodic safety-net fallback.

Fixes #866
Fixes #849
Fixes #30

Author: mPokornyETM

src/doc/examples/lock-with-timeout.md

@@ -0,0 +1,77 @@
+## Lock with allocation timeout
+
+By default, the `lock` step waits indefinitely until the requested resource becomes available.
+With `timeoutForAllocateResource` you can set a maximum wait time — if the resource is not
+acquired within that period, the build fails immediately instead of blocking the queue forever.
+
+This is useful when:
+- You prefer a fast failure over an indefinitely blocked pipeline
+- You want to detect resource starvation early
+- Your CI/CD has SLAs that cap how long a job may wait
+
+### Pipeline (scripted)
+
+```groovy
+node {
+    // Wait up to 5 minutes for the resource, then fail
+    lock(resource: 'my-printer', timeoutForAllocateResource: 5, timeoutUnit: 'MINUTES') {
+        echo "Printer locked, printing ..."
+    }
+}
+```
+
+### Pipeline (declarative)
+
+```groovy
+pipeline {
+    agent any
+    stages {
+        stage('Deploy') {
+            options {
+                lock(resource: 'staging-env', timeoutForAllocateResource: 10, timeoutUnit: 'MINUTES')
+            }
+            steps {
+                echo "Deploying to staging ..."
+            }
+        }
+    }
+}
+```
+
+### Label-based locking with timeout
+
+```groovy
+pipeline {
+    agent any
+    stages {
+        stage('Test') {
+            steps {
+                lock(label: 'phone', quantity: 1, variable: 'PHONE',
+                     timeoutForAllocateResource: 2, timeoutUnit: 'MINUTES') {
+                    echo "Running tests on ${env.PHONE}"
+                }
+            }
+        }
+    }
+}
+```
+
+### Freestyle jobs
+
+In a freestyle job configuration, go to **This build requires lockable resources** and set:
+- **Lock wait timeout**: the maximum time to wait (e.g. `5`)
+- **Timeout unit**: `SECONDS`, `MINUTES`, or `HOURS`
+
+If the resource is not available within the configured timeout, the build is automatically
+removed from the Jenkins queue.
+
+### Timeout values
+
+| `timeoutUnit` | Description |
+|---------------|-------------|
+| `SECONDS`     | Timeout in seconds |
+| `MINUTES`     | Timeout in minutes (default) |
+| `HOURS`       | Timeout in hours |
+
+Setting `timeoutForAllocateResource: 0` (the default) disables the timeout — the build
+waits indefinitely, which preserves the original behaviour.

src/doc/examples/readme.md

@@ -11,3 +11,4 @@ If you have a question, please open a [GitHub issue](https://github.com/jenkinsc
 - [Locking a random free resource](locking-random-free-resource.md)
 - [Scripted vs declarative pipeline](scripted-vs-declarative-pipeline.md)
 - [Dynamic resource pool expansion](dynamic-resource-pool-expansion.md)
+- [Lock with allocation timeout](lock-with-timeout.md)

src/main/java/org/jenkins/plugins/lockableresources/LockStep.java

@@ -66,6 +66,20 @@ public class LockStep extends Step implements Serializable {
     @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
     public int priority = 0;
 
+    /**
+     * Timeout in the specified {@link #timeoutUnit} for waiting to acquire the resource.
+     * 0 means no timeout (wait indefinitely). When the timeout expires, the step fails
+     * with an exception instead of waiting forever.
+     */
+    @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
+    public long timeoutForAllocateResource = 0;
+
+    /**
+     * Time unit for {@link #timeoutForAllocateResource}. Defaults to MINUTES.
+     */
+    @SuppressFBWarnings(value = "PA_PUBLIC_PRIMITIVE_ATTRIBUTE", justification = "Preserve API compatibility.")
+    public String timeoutUnit = "MINUTES";
+
     // it should be LockStep() - without params. But keeping this for backward compatibility
     // so `lock('resource1')` still works and `lock(label: 'label1', quantity: 3)` works too (resource
     // is not required)
@@ -142,6 +156,24 @@ public void setExtra(@CheckForNull List<LockStepResource> extra) {
         this.extra = extra;
     }
 
+    @DataBoundSetter
+    public void setTimeoutForAllocateResource(long timeoutForAllocateResource) {
+        this.timeoutForAllocateResource = Math.max(0, timeoutForAllocateResource);
+    }
+
+    @DataBoundSetter
+    public void setTimeoutUnit(String timeoutUnit) {
+        if (timeoutUnit != null && !timeoutUnit.trim().isEmpty()) {
+            // Validate it is a valid TimeUnit name
+            try {
+                java.util.concurrent.TimeUnit.valueOf(timeoutUnit.toUpperCase(Locale.ENGLISH));
+            } catch (IllegalArgumentException e) {
+                throw new IllegalArgumentException("Invalid timeoutUnit: " + timeoutUnit);
+            }
+            this.timeoutUnit = timeoutUnit.toUpperCase(Locale.ENGLISH);
+        }
+    }
+
     @Extension
     public static final class DescriptorImpl extends StepDescriptor {
 
@@ -217,6 +249,20 @@ public static FormValidation doCheckResourceSelectStrategy(
             return FormValidation.ok();
         }
 
+        @RequirePOST
+        public ListBoxModel doFillTimeoutUnitItems(@AncestorInPath Item item) {
+            if (item != null) {
+                item.checkPermission(Item.CONFIGURE);
+            } else {
+                Jenkins.get().checkPermission(Jenkins.ADMINISTER);
+            }
+            ListBoxModel items = new ListBoxModel();
+            items.add("Seconds", "SECONDS");
+            items.add("Minutes", "MINUTES");
+            items.add("Hours", "HOURS");
+            return items;
+        }
+
         @Override
         public Set<Class<?>> getRequiredContext() {
             return Collections.singleton(TaskListener.class);

src/main/java/org/jenkins/plugins/lockableresources/LockStepExecution.java

@@ -147,16 +147,22 @@ private void onLockFailed(PrintStream logger, List<LockableResourcesStruct> reso
             getContext().onSuccess(null);
         } else {
             this.printBlockCause(logger, resourceHolderList);
-            LockableResourcesManager.printLogs(
-                    "[" + step + "] is not free, waiting for execution ...", Level.FINE, LOGGER, logger);
+            String waitMsg = "[" + step + "] is not free, waiting for execution ...";
+            if (step.timeoutForAllocateResource > 0) {
+                waitMsg += " (timeout: " + step.timeoutForAllocateResource + " "
+                        + step.timeoutUnit.toLowerCase(java.util.Locale.ENGLISH) + ")";
+            }
+            LockableResourcesManager.printLogs(waitMsg, Level.FINE, LOGGER, logger);
             LockableResourcesManager lrm = LockableResourcesManager.get();
             lrm.queueContext(
                     getContext(),
                     resourceHolderList,
                     step.toString(),
                     step.variable,
                     step.inversePrecedence,
-                    step.priority);
+                    step.priority,
+                    step.timeoutForAllocateResource,
+                    step.timeoutUnit);
         }
     }
 

src/main/java/org/jenkins/plugins/lockableresources/LockableResourcesManager.java

@@ -95,6 +95,12 @@ public class LockableResourcesManager extends GlobalConfiguration {
     private transient volatile AtomicBoolean savePending;
     private transient volatile ScheduledExecutorService saveExecutor;
 
+    /** Single scheduled timeout task. Guarded by {@link #syncResources}. */
+    private transient java.util.concurrent.ScheduledFuture<?> nextTimeoutTask;
+
+    /** Deadline (epoch ms) the current {@link #nextTimeoutTask} targets. 0 = none. */
+    private transient long nextTimeoutDeadline;
+
     @DataBoundSetter
     public void setAllowEmptyOrNullValues(boolean allowEmptyOrNullValues) {
         this.allowEmptyOrNullValues = allowEmptyOrNullValues;
@@ -853,8 +859,9 @@ private QueuedContextStruct getNextQueuedContext() {
 
         LOGGER.fine("current queue size: " + this.queuedContexts.size());
         LOGGER.finest("current queue: " + this.queuedContexts);
-        List<QueuedContextStruct> orphan = new ArrayList<>();
+        List<QueuedContextStruct> toRemove = new ArrayList<>();
         QueuedContextStruct nextEntry = null;
+        long earliestDeadline = Long.MAX_VALUE;
 
         // the first one added lock is the oldest one, and this wins
 
@@ -863,18 +870,43 @@ private QueuedContextStruct getNextQueuedContext() {
             // check queue list first
             if (!entry.isValid()) {
                 LOGGER.fine("well be removed: " + idx + " " + entry);
-                orphan.add(entry);
+                toRemove.add(entry);
+                continue;
+            }
+
+            // check if the entry has timed out waiting for resources
+            if (entry.isTimedOut()) {
+                LOGGER.info("Queue entry timed out waiting for resources: " + entry);
+                toRemove.add(entry);
+                PrintStream logger = entry.getLogger();
+                String msg = "[" + entry.getResourceDescription()
+                        + "] timed out waiting for resource allocation after "
+                        + entry.getTimeoutForAllocateResource() + " "
+                        + entry.getTimeoutUnit().toLowerCase(java.util.Locale.ENGLISH);
+                printLogs(msg, logger, Level.WARNING);
+                entry.getContext()
+                        .onFailure(new org.jenkins.plugins.lockableresources.queue.LockWaitTimeoutException(msg));
                 continue;
             }
+
+            // track the earliest deadline among remaining entries for rescheduling
+            long deadline = entry.getTimeoutDeadlineMillis();
+            if (deadline > 0 && deadline < earliestDeadline) {
+                earliestDeadline = deadline;
+            }
+
             LOGGER.finest("oldest win - index: " + idx + " " + entry);
 
             nextEntry = getNextQueuedContextEntry(entry);
         }
 
-        if (!orphan.isEmpty()) {
-            this.queuedContexts.removeAll(orphan);
+        if (!toRemove.isEmpty()) {
+            this.queuedContexts.removeAll(toRemove);
         }
 
+        // reschedule for the next earliest deadline
+        scheduleTimeoutAt(earliestDeadline);
+
         return nextEntry;
     }
 
@@ -1407,6 +1439,32 @@ public void queueContext(
             String variableName,
             boolean inversePrecedence,
             int priority) {
+        queueContext(
+                context,
+                requiredResources,
+                resourceDescription,
+                variableName,
+                inversePrecedence,
+                priority,
+                0,
+                "MINUTES");
+    }
+
+    // ---------------------------------------------------------------------------
+    /*
+     * Adds the given context and the required resources to the queue if
+     * this context is not yet queued, with a timeout for resource allocation.
+     */
+    @Restricted(NoExternalUse.class)
+    public void queueContext(
+            StepContext context,
+            List<LockableResourcesStruct> requiredResources,
+            String resourceDescription,
+            String variableName,
+            boolean inversePrecedence,
+            int priority,
+            long timeoutForAllocateResource,
+            String timeoutUnit) {
         synchronized (syncResources) {
             for (QueuedContextStruct entry : this.queuedContexts) {
                 if (entry.getContext() == context) {
@@ -1416,8 +1474,14 @@ public void queueContext(
             }
 
             int queueIndex = 0;
-            QueuedContextStruct newQueueItem =
-                    new QueuedContextStruct(context, requiredResources, resourceDescription, variableName, priority);
+            QueuedContextStruct newQueueItem = new QueuedContextStruct(
+                    context,
+                    requiredResources,
+                    resourceDescription,
+                    variableName,
+                    priority,
+                    timeoutForAllocateResource,
+                    timeoutUnit);
 
             if (!inversePrecedence || priority != 0) {
                 queueIndex = this.queuedContexts.size() - 1;
@@ -1439,6 +1503,13 @@ public void queueContext(
                     Level.FINE);
 
             save();
+
+            // If this entry has a timeout and its deadline is earlier than the
+            // currently scheduled one, (re)schedule so it fires on time.
+            long deadline = newQueueItem.getTimeoutDeadlineMillis();
+            if (deadline > 0 && (nextTimeoutDeadline == 0 || deadline < nextTimeoutDeadline)) {
+                scheduleTimeoutAt(deadline);
+            }
         }
     }
 
@@ -1495,7 +1566,7 @@ public void refreshQueue() {
         // Invalidate cached candidates so waiting jobs re-evaluate with current labels
         cachedCandidates.invalidateAll();
 
-        // Process waiting pipeline jobs
+        // Process waiting pipeline jobs (also handles timeouts)
         synchronized (syncResources) {
             while (proceedNextContext()) {
                 // process as many contexts as possible
@@ -1506,6 +1577,61 @@ public void refreshQueue() {
         scheduleQueueMaintenance();
     }
 
+    // ---------------------------------------------------------------------------
+    /**
+     * Checks for timed-out entries in the pipeline lock queue and fails them.
+     * Called by {@link org.jenkins.plugins.lockableresources.queue.LockWaitTimeoutPeriodicWork}
+     * as a safety net.
+     */
+    @Restricted(NoExternalUse.class)
+    public void checkTimeouts() {
+        synchronized (syncResources) {
+            // proceedNextContext → getNextQueuedContext handles timeouts + rescheduling
+            while (proceedNextContext()) {
+                // process as many contexts as possible
+            }
+        }
+    }
+
+    // ---------------------------------------------------------------------------
+    /**
+     * Schedules (or reschedules) the single timeout task to fire at the given
+     * deadline. If {@code deadline} is {@link Long#MAX_VALUE} the current task
+     * is cancelled and nothing new is scheduled.
+     * Must be called while holding {@link #syncResources}.
+     */
+    private void scheduleTimeoutAt(long deadline) {
+        // Cancel the current task — we will either replace it or clear it
+        if (nextTimeoutTask != null) {
+            nextTimeoutTask.cancel(false);
+            nextTimeoutTask = null;
+            nextTimeoutDeadline = 0;
+        }
+
+        if (deadline == Long.MAX_VALUE || deadline <= 0) {
+            return;
+        }
+
+        nextTimeoutDeadline = deadline;
+        // Small buffer so the deadline has definitely passed when we check
+        long delayMs = Math.max(0, deadline - System.currentTimeMillis()) + 500L;
+        LOGGER.fine("Scheduling timeout check in " + delayMs + "ms");
+        nextTimeoutTask = jenkins.util.Timer.get()
+                .schedule(
+                        () -> {
+                            LOGGER.fine("Scheduled timeout check fired");
+                            synchronized (syncResources) {
+                                nextTimeoutDeadline = 0;
+                                nextTimeoutTask = null;
+                                while (proceedNextContext()) {
+                                    // process as many contexts as possible
+                                }
+                            }
+                        },
+                        delayMs,
+                        java.util.concurrent.TimeUnit.MILLISECONDS);
+    }
+
     // ---------------------------------------------------------------------------
     private AtomicBoolean getSavePending() {
         AtomicBoolean sp = savePending;