Added a findLocks step to enumerate the available resources

[gaspardpetit]

This is a companion PR to #305 to make it easier to manipulate lockable resources in pipeline. This step adds searching into the resources using a few filters:

• no argument to get all locks owned by the current build
• maching to find locks by regex
• anyOfLabels to find locks with at least one of the specified labels
• allOfLabels to find locks with all the specified labels
• noneOfLabels to find locks that do not contain any of the specified labels
• build to specify the build owning the lock. Defaults to the current build, but supports any to search everywhere (including unlocked)

In my experience, these have been enough to get around most use cases, but you could also, of course, get the whole list and filter in groovy - these are just for convenience.

My use case is to have locks defined from SCM; we want to "sync" changes (add new locks, delete removed ones) when the lock definition changes.

Combined with #305 the script would look like this:

Map resources = readYaml(file: 'resources.yaml')

// add missing / update existing
resources.each { k, v ->
  updateLock(resource:k, createResource:true, setLabels:(v.labels))
}
// delete removed
for (r in findLocks(build:'any')) {
  if (resources.contains(resource.name) == false) {
    updateLock(resource: r, deleteResource:true)
  }
}

I have another use case where I would like to be able to update resources as offline when we detect that they are not working correctly while using them:

  updateLock(resource:myFlakyResource, addLabels:'offline')

Then in another pipeline be able to periodically scan for offline resources:

findLocks(build:'any', anyOfLabels:'offline').each{ r -> 
  lock(r.name) {
    // attempt healing here
    updateLock(resource:r.name, removeLabels:'offline')
  }
}

This PR is open for discussion obviously, if others would prefer other names, other filters, etc. I was also not sure how to correctly return the resource objects to groovy in a way that would not require to unlock methods from an administrator, so I am serializing the LockableResource to a Map - it works but I have the feeling there must be a better way to marshal objects to groovy...

To fully fulfill this use case, I will also update https://github.com/jenkinsci/lockable-resources-plugin/pull/110 to provide exclusion on labels so we can do something like this:

lock(label:'printer', excludeLabel:'offline')

• [x] Make sure you are opening from a topic/feature/bugfix branch (right side) and not your main branch!
• [x] Ensure that the pull request title represents the desired changelog entry
• [x] Please describe what you did
• [x] Link to relevant issues in GitHub or Jira
• [x] Link to relevant pull requests, esp. upstream and downstream changes
• [x] Ensure you have provided tests - that demonstrates feature works or fixes the issue

[gaspardpetit]

Added a build filter and updated the description with it. This step would search for the current build's locks by default on a no-param findLocks() - but could still be used to search everywhere by doing findLocks(build:'any')

[jimklimov]

Hi, sorry for falling out of the loop, and thanks for your many PRs. One question to this one's description:

no argument to get all locks

vs.

This step would search for the current build's locks by default on a no-param ...

Which of these is supposed to be true? "all" or "this build's"? :)

[gaspardpetit]

Hi, sorry for falling out of the loop, and thanks for your many PRs. One question to this one's description:

no argument to get all locks

vs.

This step would search for the current build's locks by default on a no-param ...

Which of these is supposed to be true? "all" or "this build's"? :)

Thanks for noticing - I changed the behaviour halfway through but had not updated the original PR description. When I started using this with real-life scenarios, it became obvious that the most common use case was getting the current locks owned by the current build, so I made findLock(). To seach all locks (owned or not by this build), we have to use findLocks(build:'any')

[DonnieKim411]

please include this PR on the next release? there are many PRs created by @gaspardpetit and it will really enrich the plugin

[mPokornyETM]

One question. Will be possible to handle labels in the same way like in nodes. So don't need make own magic.

[mPokornyETM]

will be handled in #428

[mPokornyETM]

It is done by jenkins label resolver