{"id":26197278,"url":"https://github.com/mongoid/mongoid-locker","last_synced_at":"2025-04-05T00:09:58.360Z","repository":{"id":3754255,"uuid":"4829948","full_name":"mongoid/mongoid-locker","owner":"mongoid","description":"Document-level locking for MongoDB via Mongoid","archived":false,"fork":false,"pushed_at":"2024-05-07T08:57:52.000Z","size":324,"stargazers_count":77,"open_issues_count":2,"forks_count":40,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-28T23:08:19.661Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mongoid.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-06-29T07:50:44.000Z","updated_at":"2024-07-23T16:27:10.000Z","dependencies_parsed_at":"2024-06-18T17:05:23.899Z","dependency_job_id":"b12eca1f-74ec-40eb-a93d-8d0370ea440b","html_url":"https://github.com/mongoid/mongoid-locker","commit_stats":{"total_commits":167,"total_committers":14,"mean_commits":"11.928571428571429","dds":0.5089820359281437,"last_synced_commit":"3b26ba2ff5cd96047268e2f13980c5a2df961a7b"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongoid%2Fmongoid-locker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongoid%2Fmongoid-locker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongoid%2Fmongoid-locker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mongoid%2Fmongoid-locker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mongoid","download_url":"https://codeload.github.com/mongoid/mongoid-locker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266565,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-12T02:25:19.285Z","updated_at":"2025-04-05T00:09:58.344Z","avatar_url":"https://github.com/mongoid.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mongoid-Locker\n\n[![Gem Version](https://badge.fury.io/rb/mongoid-locker.svg)](https://badge.fury.io/rb/mongoid-locker)\n[![Test](https://github.com/mongoid/mongoid-locker/actions/workflows/test.yml/badge.svg)](https://github.com/mongoid/mongoid-locker/actions/workflows/test.yml)\n[![Maintainability](https://api.codeclimate.com/v1/badges/04ee4ee75ff54659300a/maintainability)](https://codeclimate.com/github/mongoid/mongoid-locker/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/04ee4ee75ff54659300a/test_coverage)](https://codeclimate.com/github/mongoid/mongoid-locker/test_coverage)\n\nDocument-level optimistic locking for MongoDB via Mongoid. Mongoid-Locker is an easy way to ensure only one process can perform a certain operation on a document at a time.\n\n**NOTE:** Since version `2` Mongoid-Locker relies on MongoDB server time and not current client time, and does not perform any time calculation to get lock or release it. The basis of the current version are unique name of locking and time is set by MongoDB.\n\n**NOTE:** Please refer to [1-x-stable](https://github.com/mongoid/mongoid-locker/tree/1-x-stable) branch for `1.x.x` documentation. See the [UPGRADING](UPGRADING.md) guide and [CHANGELOG](CHANGELOG.md) for an overview of the changes.\n\n[Tested](https://github.com/mongoid/mongoid-locker/actions) against:\n- MRI: `2.3.8`, `2.4.7`, `2.5.7`, `2.6.6`, `2.7.1`, `3.0.5`, `3.1.3`\n- JRuby `9.1.17.0`, `9.2.11.1`\n- Mongoid: `5`, `6`, `7`, `8`, `9`\n\nSee [.github/workflows/test.yml](.github/workflows/test.yml) for the latest test matrix.\n\n## Usage\n\nAdd to your `Gemfile`:\n\n```ruby\ngem 'mongoid-locker'\n```\n\nand run `bundle install`. In the model you wish to lock, include `Mongoid::Locker` after `Mongoid::Document`. For example:\n\n```ruby\nclass User\n  include Mongoid::Document\n  include Mongoid::Locker\n\n  field :locking_name, type: String\n  field :locked_at, type: Time\n\n  field :age, type: Integer\nend\n```\n\nThen, execute any code you like in a block like so:\n\n```ruby\nuser.with_lock do\n  user.age = 17\n  user.save!\nend\n```\n\nThe `#with_lock` function takes an optional handful of options, so make sure to take a look.\n\nNote that these locks are only enforced when using `#with_lock`, not at the database level. It's useful for transactional operations, where you can make atomic modification of the document with checks. For example, you could deduct a purchase from a user's balance ... _unless_ they are broke.\n\nMore in-depth method documentation can be found at [RubyDoc.info](https://www.rubydoc.info/gems/mongoid-locker).\n\n### Customizable :locking_name and :locked_at field names\nBy default, Locker uses fields with `:locking_name` and `:locked_at` names which should be defined in a model.\n```ruby\nclass User\n  include Mongoid::Document\n  include Mongoid::Locker\n\n  field :locking_name, type: String\n  field :locked_at, type: Time\nend\n```\n\nUse `Mongoid::Locker.configure` to setup parameters which used by Locker for all models where it's included.\n```ruby\nMongoid::Locker.configure do |config|\n  config.locking_name_field = :global_locking_name\n  config.locked_at_field    = :global_locked_at\nend\n\nclass User\n  include Mongoid::Document\n  include Mongoid::Locker\n\n  field :global_locking_name, type: String\n  field :global_locked_at, type: Time\nend\n```\n\nThe `locker` method in your model accepts options to setup parameters for the model.\n```ruby\nclass User\n  include Mongoid::Document\n  include Mongoid::Locker\n\n  field :locker_locking_name, type: String\n  field :locker_locked_at, type: Time\n\n  locker locked_at_field: :locker_locking_name,\n         locked_at_field: :locker_locked_at\nend\n```\n\n### Available parameters for Mongoid::Locker, a class where it's included\n| parameter | default | options | description |\n|---|---|---|---|\n| locking_name_field | `:locking_name` | any field name | field where name of locking is storing, must be of type `String` |\n| locked_at_field | `:locked_at` | any field name | field where it is storing the time of beginning a lock of a document, must be of type `Time` |\n| lock_timeout | `5` | | within this time (in seconds) a document is considered as locked |\n| locker_write_concern | `{ w: 1 }` | see [MongoDB Write Concern](https://docs.mongodb.com/manual/reference/write-concern/#write-concern-specification)| a write concern only used for lock and unlock operations |\n| maximum_backoff | `60.0` | | the highest timeout (in seconds) between retires to lock a document, reaching that value `#with_lock` method raises `Mongoid::Locker::Errors::DocumentCouldNotGetLock` |\n| backoff_algorithm | `:exponential_backoff` | `:locked_at_backoff` or [custom algorithm](#custom-backoff_algorithm-and-locking_name_generator) | algorithm used for timeout calculating between retries to lock a document|\n| locking_name_generator | `:secure_locking_name` | [custom generator](#custom-backoff_algorithm-and-locking_name_generator) | generator used to generate unique name of a lock |\n\nFor instances of a class where `Mongoid::Locker` is included, all parameters of a class are available for reading.\n```ruby\n  document.lock_timeout\n  #=\u003e 5\n```\n\n### Custom :backoff_algorithm and :locking_name_generator\nA method which is defined in `Mongoid::Locker` are available in a class where it is included.\n\nMethod `#with_lock` passes to the methods a document to which apply `#with_lock` and a hash of options. The hash may look like this:\n```ruby\n  { retries: Infinity, reload: true, attempt: 0, locking_name: \"71c1ccd4-72d9-4a83-bbed-adf65803bd5d\" }\n```\n\nA custom backoff algorithmoff **must return** a value more or equal `maximum_backoff` value to force `#with_lock` quit trying to lock a document, otherwise `#with_lock` will be trying to lock a document `INFINITY` times.\n```ruby\nMongoid::Locker.configure do |config|\n  config.backoff_algorithm = :custom_backoff\nend\n\nmodule Mongoid\n  module Locker\n    def self.custom_backoff(doc, _opts)\n      rand \u003e 0.5 ? 5 : doc.maximum_backoff\n    end\n  end\nend\n```\n\nA custom locking name generator **must return** a string to secure uniqueness name of locking.\n```ruby\nclass User\n  include Mongoid::Document\n  include Mongoid::Locker\n\n  locker locking_name_generator: :custom_locking_name\n\n  field :locker_locking_name, type: String\n  field :locker_locked_at, type: Time\n\n  def self.custom_locking_name(_doc, _opts)\n    SecureRandom.uuid\n  end\n```\n\n## Testing with RSpec\nPlease see examples in [test_examples_spec.rb](spec/test_examples_spec.rb) file.\n\n## Copyright \u0026 License\n\nCopyright (c) 2012-2020 Aidan Feldman \u0026 Contributors\n\nMIT License, see [LICENSE](LICENSE.txt) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongoid%2Fmongoid-locker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmongoid%2Fmongoid-locker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmongoid%2Fmongoid-locker/lists"}