SCSP Headers
Header Limits: Headers (metadata) are constrained not only by Swarm but by all services, proxies, and clients (such as Elasticsearch, Twisted, Jetty, HAProxy) handling objects. A Swarm object may have any number of annotations associated with it, but each annotation object is subject to these limits. The persisted metadata on Swarm objects must fall within these limits by default:
500 - The total number of headers on an object
32 KB - The combined length of all headers (key/value pairs); exceeding this returns a 400 (Bad Request) error
16 KB - The maximum length for a given header (key/value pair)
The following tables list all headers supported or used by Swarm. The headers described apply to buckets, named objects, and aliased objects unless otherwise noted.
Methods are the SCSP methods to which the header applies.
Request (signified by X)
Response (signified by X)
V means it appears only with
verbose=true
T means it appears in a trailing response
Writable (signified by W)
R means it is read-only
Persisted indicates whether the header is persisted with the object. Note: some persisted headers are not writable (signified by P).
Best Practice
Always use case-insensitive header matching.
Swarm-Specific Headers
Header | Description | Method | Request | Response [Trailing] [Verbose] | Writable [Read-only] | Persisted |
---|---|---|---|---|---|---|
Castor-System-Accessed | Used on GET/HEAD requests to indicate the time the object was last accessed (written or GET). | GET, HEAD | X V | |||
Castor-System-CompositeMD5 | Multipart-written objects only. This composite value, stored with the completed object, is computed on the multipart complete as the sum of the Content-MD5 values of all parts. This header value is reused on subsequent COPY operations but removed on other updates (PUT, APPEND). | GET, HEAD, POST | T | |||
Castor-System-Decorates | Set to the ETag of a Swarm object to be decorated. When the decorated object is deleted or overwritten, the object with this header is reclaimed by the health processor. | All | X | X | W | P |
Castor-System-Headers-Filtered | If response headers are filtered by a whitelist or blacklist, this header is added. | GET, HEAD | X | R | ||
Castor-System-InProgress | Returned with value yes on a verbose request when the inprogress flag is set on a stream. Not returned at all when the flag is not set. | GET, HEAD | X V | |||
Castor-System-Result | Reports the response code, such as 201 (Created) or 404 (Not Found), as a trailing header for a multipart write completion. | POST | T | |||
Castor-System-Tiered | Audit headers for objects restored by an S3 Backup feed. One copy captures the date and source cluster of the backup, and another captures the date and S3 host/bucket of the restore. Dates are same format as Last-Modified. | GET, HEAD | X V | R | P | |
Castor‑{anything} | {anything} cannot start with "system". Uninterpreted; meant for client customization. | All | W | P | ||
Castor‑Authorization | Content‑level authorization. | All | X | W | P | |
Castor‑System-Bytes‑Used | With bucket list du, the number of bytes in the query without replicas. | GET (listing) | X | |||
Castor‑System-Bytes‑Used‑With‑Reps | With bucket list du / withreps requests, the number of bytes in the query with replicas. | GET (listing) | X | |||
Castor‑System-Object‑Count | In a bucket listing request, the number of objects returned by the query. | X | ||||
Castor‑System‑Alias | The alias UUID of an alias object, bucket, or domain. This UUID cannot be used in any SCSP method on a domain, bucket, or named object. Use it to execute SCSP methods on an aliased object or to delete an unnamed immutable object. | GET, HEAD, DELETE | X | R | P | |
Castor‑System‑Auth | Special headers for a GET/retrieve request. The username:password for an administrative account on the remote cluster, only if it differs from the source cluster. | SEND | X | |||
Castor‑System‑CID | For named and tenanted unnamed objects, the alias UUID of the owning context. | GET, HEAD, DELETE | X | R | P | |
Castor‑System‑Cluster | Name of the cluster where the object was created or last updated. For SEND, The value of the cluster.name setting of the destination cluster. | GET, HEAD, DELETE, SEND | X | R | P | |
Castor‑System‑Created | A timestamp that specifies when the object was created or last updated. Uses HTTP time, an ASCII format based on GMT. | GET, HEAD, DELETE | X | R | P | |
Castor‑System‑Domain | Named objects only. Shows the name of the domain where the object was created. The domain name in which this object is tenanted. Computed on GET and HEAD. Returns <domain>. | GET, HEAD | X V | R | P | |
Castor‑System‑EnforceTenancy | True or False depending on cluster.enforceTenancy. A response header on the status page. | GET | X | |||
Castor‑System‑Error‑Code | Sent with any error response. The request error code (if applicable). This code is usually a 4xx or 5xx HTTP response code. May appear as a trailing header on multipart write complete requests. | All | X | |||
Castor‑System‑Error‑Text | Sent with any error response. The request error description (if applicable). Provides a description of the error. May appear as a trailing header on multipart write complete requests. | All | X | |||
Castor‑System‑Error‑Token | Sent with any error response. A unique error token (if applicable). Provides a parsed token that uniquely identifies the error. May appear as a trailing header on multipart write complete requests. | All | X | |||
Castor‑System‑IsVersioned | Header indicating the object versioning state in effect at the time the object was written. May only appear on alias or named objects. True if the object was written in the versioning‑Enabled state. "False" if the object was written in the versioning‑Suspended state. There is no header otherwise. A flag for the object's Swarm versioning status, which does not appear on objects created in a versioning‑disabled context. True means it was created in the versioning‑Enabled state. False means it was created in the versioning‑Suspended state. | GET, HEAD | R | P | ||
Castor‑System‑LicenseCapacityTB | Return on a cluster status request. Indicates the licensed capacity, in TB. | X | ||||
Castor‑System‑LicenseSerialNumber | Returned on a cluster status request. Indicates the license serial number, or 'unregistered.' | X | ||||
Castor‑System‑Name | Named objects only. Symbolic name of the object, which is the user‑Specified (partial) name for this object. | GET, HEAD, DELETE | X | R | P | |
Castor‑System‑Next‑Version | Appears only on admin or administrative GET or HEAD responses. When object versioning is enabled or suspended, named and alias objects include these headers if there is a previous or next version in the version chain for the object. | GET, HEAD | X V | |||
Castor‑System‑Owner | The user id of the authenticated user who wrote the object. Name of the user who created or last modified the object. If the object was created anonymously (that is, without authenticating), this header is absent. | All | R | P | ||
Castor‑System‑PartNumber | Special headers for multipart write requests. Identifies the part number of a part in the temporary manifest for a multipart write. | POST, PUT | X | W | P | |
Castor‑System‑Path | For named objects only, shows the full path of the object in /domain/bucket/object format. Example: /cluster.example.com/mybucket/mypath/myobject.html. Computed on GET and HEAD. Returns <domain>/<bucket>/<name>. | GET, HEAD | X V | R | P | |
Castor‑System‑Persisted-Headers | Indicates which of the other headers on the response are persisted. | GET, HEAD | X V | |||
Castor‑System‑Previous‑Version | Appears only on admin or administrative GET or HEAD responses. When object versioning is enabled or suspended, named and alias objects include these headers if there is a previous or next version in the version chain for the object. | GET, HEAD | X V | |||
Castor‑System‑TotalGBAvailable | A response header on the status page. | GET | X | |||
Castor‑System‑TotalGBCapacity | A response header on the status page. | GET | X | |||
Castor‑System‑UploadID | Special header for multipart write requests. As a response header, it identifies the multipart write request for all subsequent requests relating to the upload. As a persisted header, it associates a stream with a multipart upload, either as the init stream or a part, based on its Castor-System-PartNumber value. | GET, HEAD | X | R | P | |
Castor‑System‑Version | A numerical version number associated with mutable objects. This is a UNIX‑Style floating point time since GMT epoch with millisecond accuracy. The timestamp (in seconds since epoch) when the object was written, which corresponds to Last‑Modified. Not writable: Although it is persisted, this header cannot be supplied on any non‑admin requests. | All | X | R | P | |
Composite-Content-MD5 | Provides an end‑to‑end integrity check of the content (excluding metadata) of a parallel write request at the time of completion. The supplied value is a base-64 encoding of the concatenation of the binary Content-MD5 hashes of the parts (in order) followed by a dash, followed by the number of parts as text value. On the complete request, Swarm computes the value for the overall request and reject the request with a 409 error if the values do not match. | POST | X | X | W | P |
Content-MD5 | Users can compute the md5 sum of the object prior to write. The header is preserved and checked on GET. A persisted Content-MD5 can also be generated by Swarm. | POST, PUT, GET, HEAD | X | X | W | P |
Content-type: | Required to create a context. Content-Type is a standard HTTP header. | POST, PUT | X | |||
Content‑UUID | One header per UUID specified. Indicates the alias or primary uuid from a diskless countrep HEAD request. Also on a write request indicating the new content uuid. Unnamed objects only. COPY and PUT are invalid methods for immutable objects. Not writable: Although it is persisted, this header cannot be supplied on any non‑admin requests. Is returned as a trailing header on multipart write completes. | All | X | W | P | |
Feed‑{id}‑Status | On a verbose GET or HEAD, returns the status of each defined feed, one per header. The {id} is the ID field from the feed definition. The value is 0 for success (no writes remaining), 1 for timeout, or else the number of attempts made to write the object. | GET, HEAD | X V | |||
Feed‑{id}‑StatusTime | On a verbose GET or HEAD, returns the status time of each defined feed, one per header. Time is HTTP time. | GET, HEAD | X V | |||
Lifepoint | Time‑based SCSP and HP directives. Returned for an object created with a lifepoint header. | All | X | X | W | P |
Manifest | Indicates the object is erasure coded. Indicates the manifest type of the object being created or queried. Internal. Used with replica transfer. Currently, "ec" is the only value used. Indicates the manifest type of the object being created or queried. Also returned on a verbose GET/HEAD for EC objects. | All | X V | |||
Node-Status | Return on a cluster status request. Indicates the current node status. | X | ||||
Overlay‑IPs | A list of space‑separated IP addresses associated with the overlay key. Only on a countreps HEAD request. Up to two IP headers may appear. | X | ||||
Overlay‑Key | An overlay index key used for this object. Only on a countreps HEAD request. Up to two keys may appear. | X | ||||
Policy-* | Include Policy-* headers in the header inclusion list or use the preserve query argument for COPY. | COPY | W | P | ||
Policy-ECEncoding | Optional; context objects only. Stores the encoding policy for erasure coding named objects in this context. Valid values: unspecified, disabled, k:p (a tuple such as 5:2 that specifies the data and parity encoding to use). For a domain, appending "anchored" cancels any policies on its buckets. | All | X | X | W | P |
Policy-ECEncoding-Unnamed | Optional; domain objects only. Stores the encoding policy for erasure coding unnamed objects tenanted in this domain. Valid values: unspecified, disabled, k:p (a tuple such as 5:2 that specifies the data and parity encoding to use). | All | X | X | W | P |
Policy-ECMinStreamSize | Optional; context objects only. Stores the minimum object size that triggers erasure coding of named objects in this context. In units of megabytes (MB) or gigabytes (GB); must be 1MB (default) or greater. For a domain, appending "anchored" cancels any policies on its buckets. |