xapi_rs

Module resources

Source
Expand description

Endpoints grouped by Resource.

§General requirements

  • When responding to a GET, LaRS adds an ETag header to the response.
  • When responding to a PUT, POST, or DELETE request, LaRS handles the If-Match and If-None-Match headers as described in RFC 2616 to detect changes made since the targeted resource was last modified.

If request pre-conditions fail, LaRS:

  • Returns a 412 Precondition Failed status, and
  • Does not modify the targeted resource.

If a PUT request is received without If-Match or If-None-Match headers for a resource that already exists, LaRS:

  • Returns a 409 Conflict status,
  • Does not modify the targeted resource.

§About If-Match and If-None-Match headers

It can get easily confusing making sense of what “pass” and “fail” mean for the pre-conditions introduced by those headers. I’ll try to describe here the logic that i apply dealing w/ them when handling GET, PUT, POST, and DELETE verbs as i understood it from the MDN online documentation of said headers.

I didn’t mention the case of HEAD b/c Rocket handles this1 automatically based on what the GET does.

§If-Match header 2

The If-Match HTTP request header makes a request conditional.

LaRS will only return requested resources for GET and HEAD methods, or upload resource for PUT and other non-safe methods, if the resource matches one of the listed ETag values. If the conditional does not match then 412 (Precondition Failed) response is returned.

The comparison with the stored ETag uses the strong comparison algorithm, meaning two files are considered identical byte by byte only. If a listed ETag has the W/ prefix indicating a weak entity tag, this comparison algorithm will never match it.

§If-None-Match header 3

The If-None-Match HTTP request header makes the request conditional.

  • For GET and HEAD methods, LaRS will return the requested resource, with a 200 status, only if it doesn’t have an ETag matching the given ones.
  • For other methods, the request will be processed only if the eventually existing resource’s ETag doesn’t match any of the values listed.

When the condition fails for GET and HEAD methods, LaRS returns HTTP status code 304 (Not Modified). For methods that apply server-side changes, the status code 412 (Precondition Failed) is returned.

  1. https://rocket.rs/guide/v0.5/requests/#head-requests ↩

  2. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Match ↩

  3. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match ↩

Modules§

about
About Resource (/about)
activities
Activities Resource (/activities)
activity_profile
Activity Profile Resource (/activities/profile)
agent_profile
Agent Profile Resource (/agents/profile)
agents
Agents Resource (/agents)
state
State Resource (/activities/state)
statement
Statement Resource (/statements)
stats
Track some basic statistics per route. The metrics we collect here are:
users
User Management Extension
verbs
Verbs extension

Macros§

emit_response
Given $resource of type $type that is serde Serializable and $headers (an instance of a type that handles HTTP request headers)…
eval_preconditions
Given an $etag (Entity Tag) value and $headers (an instance of a type that handles HTTP request headers), check that the If-XXX pre- conditions when present, pass.