How to update metadata headers

Problem

You need to modify the headers on an object, such as to update Swarm permissions or modify a lifepoint.

Solution

Swarm provides a COPY extension method to allow users to change headers without changing content. Using it, though, can be tricky.

COPY modifies all headers at once, so simply calling COPY with your new header or modified header value will drop all other user-supplied headers that were originally set on the object. To do it correctly, you need to HEAD the original object, grab all writable, persistent headers, and COPY the object with those header values plus any new ones and less any you want to remove.

Persistent User-Writable Swarm Headers

The following list is current as of Swarm 8.0. Note that Swarm 8.0 added Policy-Versioning to the persistent user-writable set from 7.5.

Allow
Cache-Control
Content-Encoding
[Content-Length] (See note below on Content-Length)
[Content-MD5] (See note below on Content-MD5)
Lifepoint (See note below on Lifepoints with EC Specs)
[Policy-<anything>] (See note below on Policy-*)
Allow-Encoding
Castor-[anything] (See note below on Custom Metadata headers)
Content-Language
Content-Location
Content-Base
Content-Type
Content-Disposition
Expires
X-[anything]-Meta[-anything] (See note below on Custom Metadata headers)

Custom Metadata Headers (Castor-[anything] and X-[anything]-Meta[-anything]

Swarm recognizes custom headers of the formats X-[*]-Meta[-*] and Castor-[*], excluding Castor-System[*]. However, you should not use the following header names, which have meaning to Swarm or Swarm Search. Never send these on POST, PUT, or COPY:

Castor-System-*
Castor-Object-Count
Castor-Bytes-Used
Castor-Bytes-Used-With-Reps
X-Castor-Meta-Error-Message

Additionally, Swarm recognizes the Castor-Authorization as the authorization specification for objects and contexts. It should never contain anything but a valid Swarm auth spec. Use this header with caution.

Content-MD5

Swarm fails a COPY request with Content-MD5 if the object is stored erasure-coded and the Content-MD5 wasn't stored in the original POST or PUT. Don't try to add Content-MD5 with a COPY to an EC object. Include it in your COPY for both erasure-coded and non-erasure-coded objects if it already existed on the object.

Content-Length

Swarm does not update Content-Length on a COPY, and it fails any COPY requests with a Content-Length > 0. Do not send this header on a COPY unless it has the value 0.

Policy-*

Swarm releases after 8.0 will add additional Policy-<Feature> headers. In the code that you write for 8.0+, have your header inclusion list for COPY include all Policy-* headers except for Policy-Versioning-Evaluated (which is set by Swarm). Swarm recognizes, stores, and returns Policy-Versioning for contexts only (domain and bucket objects).

Lifepoints with EC Specs

Swarm 8.0 returns a 400 Bad Request response on requests with Lifepoints with EC specifications, regardless of whether the object already has the same Lifepoint set on it or is currently stored with the same EC spec values. This means that all COPY requests must remove all Lifepoints with EC specs.

Content Gateway Transforms

Content Gateway allows domain admins to specify header transformations for POSTs, PUTs, and COPYs. A COPY sent through Content Gateway is subject to the transform rules, replacing all headers that match the applicable transform rule header names with values in the rules. This implies two things:

Content Gateway will discard any headers in a COPY request that match transform rules.
Content Gateway will update any headers specified in a transform rules with current request values for rule Substitution Variables. That is, COPY will replace date and user variables with the current request values rather than the original values on the object.