platform/api/symfony/Component/Lock/Store/MongoDbStore.yaml
2024-09-02 10:44:11 -07:00

277 lines
10 KiB
YAML

name: MongoDbStore
class_comment: "# * MongoDbStore is a StoreInterface implementation using MongoDB\
\ as a storage\n# * engine. Support for MongoDB server >=2.2 due to use of TTL indexes.\n\
# *\n# * CAUTION: TTL Indexes are used so this store relies on all client and server\n\
# * nodes to have synchronized clocks for lock expiry to occur at the correct\n\
# * time. To ensure locks don't expire prematurely; the TTLs should be set with\n\
# * enough extra time to account for any clock drift between nodes.\n# *\n# * CAUTION:\
\ The locked resource name is indexed in the _id field of the lock\n# * collection.\
\ An indexed field's value in MongoDB can be a maximum of 1024\n# * bytes in length\
\ inclusive of structural overhead.\n# *\n# * @see https://docs.mongodb.com/manual/reference/limits/#Index-Key-Limit\n\
# *\n# * @author Joe Bennett <joe@assimtech.com>\n# * @author J\xE9r\xF4me Tamarelle\
\ <jerome@tamarelle.net>"
dependencies:
- name: UTCDateTime
type: class
source: MongoDB\BSON\UTCDateTime
- name: Client
type: class
source: MongoDB\Client
- name: Collection
type: class
source: MongoDB\Collection
- name: Database
type: class
source: MongoDB\Database
- name: BulkWrite
type: class
source: MongoDB\Driver\BulkWrite
- name: Command
type: class
source: MongoDB\Driver\Command
- name: WriteException
type: class
source: MongoDB\Driver\Exception\WriteException
- name: Manager
type: class
source: MongoDB\Driver\Manager
- name: Query
type: class
source: MongoDB\Driver\Query
- name: DriverRuntimeException
type: class
source: MongoDB\Exception\DriverRuntimeException
- name: MongoInvalidArgumentException
type: class
source: MongoDB\Exception\InvalidArgumentException
- name: UnsupportedException
type: class
source: MongoDB\Exception\UnsupportedException
- name: InvalidArgumentException
type: class
source: Symfony\Component\Lock\Exception\InvalidArgumentException
- name: InvalidTtlException
type: class
source: Symfony\Component\Lock\Exception\InvalidTtlException
- name: LockAcquiringException
type: class
source: Symfony\Component\Lock\Exception\LockAcquiringException
- name: LockConflictedException
type: class
source: Symfony\Component\Lock\Exception\LockConflictedException
- name: LockExpiredException
type: class
source: Symfony\Component\Lock\Exception\LockExpiredException
- name: LockStorageException
type: class
source: Symfony\Component\Lock\Exception\LockStorageException
- name: Key
type: class
source: Symfony\Component\Lock\Key
- name: PersistingStoreInterface
type: class
source: Symfony\Component\Lock\PersistingStoreInterface
- name: ExpiringStoreTrait
type: class
source: ExpiringStoreTrait
properties: []
methods:
- name: __construct
visibility: public
parameters:
- name: mongo
- name: options
default: '[]'
- name: initialTtl
default: '300.0'
comment: "# * MongoDbStore is a StoreInterface implementation using MongoDB as a\
\ storage\n# * engine. Support for MongoDB server >=2.2 due to use of TTL indexes.\n\
# *\n# * CAUTION: TTL Indexes are used so this store relies on all client and\
\ server\n# * nodes to have synchronized clocks for lock expiry to occur at the\
\ correct\n# * time. To ensure locks don't expire prematurely; the TTLs should\
\ be set with\n# * enough extra time to account for any clock drift between nodes.\n\
# *\n# * CAUTION: The locked resource name is indexed in the _id field of the\
\ lock\n# * collection. An indexed field's value in MongoDB can be a maximum of\
\ 1024\n# * bytes in length inclusive of structural overhead.\n# *\n# * @see https://docs.mongodb.com/manual/reference/limits/#Index-Key-Limit\n\
# *\n# * @author Joe Bennett <joe@assimtech.com>\n# * @author J\xE9r\xF4me Tamarelle\
\ <jerome@tamarelle.net>\n# */\n# class MongoDbStore implements PersistingStoreInterface\n\
# {\n# use ExpiringStoreTrait;\n# \n# private Manager $manager;\n# private string\
\ $namespace;\n# private string $uri;\n# private array $options;\n# \n# /**\n\
# * @param Collection|Client|Manager|string $mongo An instance of a Collection\
\ or Client or URI @see https://docs.mongodb.com/manual/reference/connection-string/\n\
# * @param array $options See below\n# * @param\
\ float $initialTtl The expiration delay of locks in\
\ seconds\n# *\n# * @throws InvalidArgumentException If required options are not\
\ provided\n# * @throws InvalidTtlException When the initial ttl is not valid\n\
# *\n# * Options:\n# * gcProbability: Should a TTL Index be created expressed\
\ as a probability from 0.0 to 1.0 [default: 0.001]\n# * database: The\
\ name of the database [required when $mongo is a Client]\n# * collection:\
\ The name of the collection [required when $mongo is a Client]\n# * uriOptions:\
\ Array of uri options. [used when $mongo is a URI]\n# * driverOptions:\
\ Array of driver options. [used when $mongo is a URI]\n# *\n# * When using a\
\ URI string:\n# * The database is determined from the uri's path, otherwise\
\ the \"database\" option is used. To specify an alternate authentication database;\
\ \"authSource\" uriOption or querystring parameter must be used.\n# * The\
\ collection is determined from the uri's \"collection\" querystring parameter,\
\ otherwise the \"collection\" option is used.\n# *\n# * For example: mongodb://myuser:mypass@myhost/mydatabase?collection=mycollection\n\
# *\n# * @see https://docs.mongodb.com/php-library/current/reference/method/MongoDBClient__construct/\n\
# *\n# * If gcProbability is set to a value greater than 0.0 there is a chance\n\
# * this store will attempt to create a TTL index on self::save().\n# * If you\
\ prefer to create your TTL Index manually you can set gcProbability\n# * to 0.0\
\ and optionally leverage\n# * self::createTtlIndex(int $expireAfterSeconds =\
\ 0).\n# *\n# * writeConcern and readConcern are not specified by MongoDbStore\
\ meaning the connection's settings will take effect.\n# * readPreference is primary\
\ for all queries.\n# * @see https://docs.mongodb.com/manual/applications/replication/"
- name: skimUri
visibility: private
parameters:
- name: uri
comment: '# * Extract default database and collection from given connection URI
and remove collection querystring.
# *
# * Non-standard parameters are removed from the URI to improve libmongoc''s re-use
of connections.
# *
# * @see https://www.php.net/manual/en/mongodb.connection-handling.php'
- name: createTtlIndex
visibility: public
parameters:
- name: expireAfterSeconds
default: '0'
comment: '# * Creates a TTL index to automatically remove expired locks.
# *
# * If the gcProbability option is set higher than 0.0 (defaults to 0.001);
# * there is a chance this will be called on self::save().
# *
# * Otherwise; this should be called once manually during database setup.
# *
# * Alternatively the TTL index can be created manually on the database:
# *
# * db.lock.createIndex(
# * { "expires_at": 1 },
# * { "expireAfterSeconds": 0 }
# * )
# *
# * Please note, expires_at is based on the application server. If the
# * database time differs; a lock could be cleaned up before it has expired.
# * To ensure locks don''t expire prematurely; the lock TTL should be set
# * with enough extra time to account for any clock drift between nodes.
# *
# * A TTL index MUST BE used to automatically clean up expired locks.
# *
# * @see http://docs.mongodb.org/manual/tutorial/expire-data/
# *
# * @throws UnsupportedException if options are not supported by the
selected server
# * @throws MongoInvalidArgumentException for parameter/option parsing errors
# * @throws DriverRuntimeException for other driver errors (e.g. connection
errors)'
- name: save
visibility: public
parameters:
- name: key
comment: '# * @throws LockExpiredException when save is called on an expired lock'
- name: putOffExpiration
visibility: public
parameters:
- name: key
- name: ttl
comment: '# * @throws LockStorageException
# * @throws LockExpiredException'
- name: delete
visibility: public
parameters:
- name: key
comment: null
- name: exists
visibility: public
parameters:
- name: key
comment: null
- name: upsert
visibility: private
parameters:
- name: key
- name: ttl
comment: '# * Update or Insert a Key.
# *
# * @param float $ttl Expiry in seconds from now'
- name: isDuplicateKeyException
visibility: private
parameters:
- name: e
comment: null
- name: getManager
visibility: private
parameters: []
comment: null
- name: createMongoDateTime
visibility: private
parameters:
- name: seconds
comment: '# * @param float $seconds Seconds since 1970-01-01T00:00:00.000Z supporting
millisecond precision. Defaults to now.'
- name: getUniqueToken
visibility: private
parameters:
- name: key
comment: '# * Retrieves a unique token for the given key namespaced to this store.
# *
# * @param Key $key lock state container'
traits:
- MongoDB\BSON\UTCDateTime
- MongoDB\Client
- MongoDB\Collection
- MongoDB\Database
- MongoDB\Driver\BulkWrite
- MongoDB\Driver\Command
- MongoDB\Driver\Exception\WriteException
- MongoDB\Driver\Manager
- MongoDB\Driver\Query
- MongoDB\Exception\DriverRuntimeException
- MongoDB\Exception\UnsupportedException
- Symfony\Component\Lock\Exception\InvalidArgumentException
- Symfony\Component\Lock\Exception\InvalidTtlException
- Symfony\Component\Lock\Exception\LockAcquiringException
- Symfony\Component\Lock\Exception\LockConflictedException
- Symfony\Component\Lock\Exception\LockExpiredException
- Symfony\Component\Lock\Exception\LockStorageException
- Symfony\Component\Lock\Key
- Symfony\Component\Lock\PersistingStoreInterface
- ExpiringStoreTrait
interfaces:
- PersistingStoreInterface