Concurrency¶
rn_forge.web.concurrency
¶
ETag codecs and If-Match checks for optimistic concurrency.
Version mismatches produce 412, required missing preconditions produce 428,
and malformed validators produce 400. Version codecs accept weak validators
and If-Match: * only.
ANY_ETAG = '*'
module-attribute
¶
If-Match: * — matches any current representation (RFC 9110 §13.1.1).
DEFAULT_CODEC = EntityVersionETagCodec()
module-attribute
¶
The codec :func:check_precondition uses when the caller names none.
ETagCodec
¶
Bases: Protocol
Formats and parses the ETag validator carried in If-Match.
format(*, entity_id, version)
¶
Return the ETag validator for an entity at a version.
parse(raw)
¶
Parse a validator into (entity_id or None, version).
Raises:
| Type | Description |
|---|---|
MalformedPrecondition
|
raw is not a validator this codec emits. |
EntityVersionETagCodec
¶
W/"<entity_id>:<version>" — the default.
Carrying the entity id catches a client replaying a precondition from a different entity, which the version alone cannot.
The entity segment is deliberately any run of characters that is not a
colon or a quote, not a UUID pattern: integer and slug primary keys are
both real, and rn_forge.django.BaseModel does not have a UUID pk. That
relaxation is intentional.
format(*, entity_id, version)
¶
Return W/"<entity_id>:<version>".
Raises:
| Type | Description |
|---|---|
MalformedPrecondition
|
entity_id renders with a |
parse(raw)
¶
Parse W/"<entity_id>:<version>" into (entity_id, version).
VersionETagCodec
¶
W/"<version>" — carries no entity identity.
For models without a stable public id to put in the validator. It cannot
catch a precondition replayed from a different entity; prefer
:class:EntityVersionETagCodec where an id is available.
check_item_precondition(item, *, current_version, entity_id, codec, required)
¶
Raise unless a :batchUpdate item's ifMatch matches the current state.
Checks item.if_match as :func:check_precondition checks an
If-Match header, and raises the same exception for the same input,
with an errors entry pointing at /requests/<index>/ifMatch.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
item
|
BatchUpdateItem
|
The item to check. |
required |
current_version
|
int
|
The entity's current version. |
required |
entity_id
|
object
|
The entity's id, compared when the codec carries one. |
required |
codec
|
ETagCodec
|
The validator format. |
required |
required
|
bool
|
When |
required |
Raises:
| Type | Description |
|---|---|
PreconditionRequired
|
The item has no |
MalformedPrecondition
|
The |
VersionConflict
|
The version, or the entity id, does not match. |
check_precondition(raw_if_match, *, current_version, entity_id=None, codec=DEFAULT_CODEC, required=False)
¶
Raise unless the client's precondition matches the current state.
Deliberately strict about the validator's syntax: anything it cannot parse is a 400, never a crash.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw_if_match
|
str | None
|
The raw |
required |
current_version
|
int
|
The entity's current version. |
required |
entity_id
|
object | None
|
The entity's id, compared when the codec carries one. |
None
|
codec
|
ETagCodec
|
The validator format. Defaults to :class: |
DEFAULT_CODEC
|
required
|
bool
|
When |
False
|
Raises:
| Type | Description |
|---|---|
PreconditionRequired
|
raw_if_match is |
MalformedPrecondition
|
The header is present but unparseable. |
VersionConflict
|
The version, or the entity id, does not match. |
is_not_modified(if_none_match, etag)
¶
Return whether etag satisfies an inbound If-None-Match (RFC 9110 §13.1.2).
For a GET/HEAD whose caller already holds a cached representation:
a match means the caller sends 304 with no body and the ETag repeated
(RFC 9110 §15.4.5). Comparison is weak — a leading W/ is ignored on
both sides — unlike :func:check_precondition's If-Match, which RFC
9110 requires to compare strongly by default; ETags in this kit are always
weak, so the distinction is moot here but the rule is still the caller's
to get right for a strong validator from elsewhere.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
if_none_match
|
str | None
|
The raw |
required |
etag
|
str
|
The resource's current ETag validator. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
|
bool
|
comma-separated list weakly matches etag. |