Skip to content

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 : or ", which would produce a validator this codec cannot parse back.

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.

format(*, entity_id, version)

Return W/"<version>". entity_id is accepted and ignored.

parse(raw)

Parse W/"<version>" into (None, version).

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 True, an item without ifMatch is an error.

required

Raises:

Type Description
PreconditionRequired

The item has no ifMatch and required.

MalformedPrecondition

The ifMatch is unparseable.

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 If-Match header value, or None.

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:EntityVersionETagCodec.

DEFAULT_CODEC
required bool

When True, an absent header is an error. Making preconditions mandatory is the caller's choice, per route.

False

Raises:

Type Description
PreconditionRequired

raw_if_match is None and required.

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 If-None-Match header value, or None.

required
etag str

The resource's current ETag validator.

required

Returns:

Type Description
bool

True when if_none_match is *, or any validator in its

bool

comma-separated list weakly matches etag.