Module resources

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 this¹ automatically based on what the GET does.

If-Match header ²

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 ³

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)

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.