This section provides general information about SCSP COPY applicable to both named and alias objects. Immutable unnamed objects cannot have associated metadata updated.

The COPY method allows updating the metadata on an object after the initial write. COPY allows changing headers without changing content, such as updating permissions or change a lifepoint. The COPY method does not create any new objects: rather, it updates the metadata on an existing object, by copying the content verbatim while replacing the metadata.

Best Practice

COPY modifies all headers at once, so calling COPY with a new or modified header value has the effect of dropping all other user-supplied headers originally set on the object.

To use COPY correctly, follow this process:

HEAD the original object.
Grab all writable persisted headers (see "Headers to preserve", below).
COPY the object with those header values, with these changes:
1. Add any new headers or updated values.
2. Omit any headers to be removed.

The requestor decides exactly which headers are written. The COPY method returns a response after the object update is complete.

Update Frequency

Named and alias objects can be updated at a maximum frequency of once per second. Updating more frequently can cause unpredictable results with the stored object version. Include the replicate query argument to verify more than one node can return the latest version in a subsequent read if an application updates objects faster than once per second.

Gateway Transforms

In the Gateway, domain admins can specify header transformations for POSTs, PUTs, and COPYs. A COPY sent through the Gateway is subject to the transform rules, replacing all headers matching the applicable transform rule header names with values in the rules. Gateway discards any headers in a COPY request matching transform rules and updates those headers with current request values for rule Substitution Variables. COPY replaces date and user variables with the current request values rather than the original values on the object.

Headers to Preserve

Following are persisted headers typically preserved when adding metadata to an object:

Allow
Cache‑Control
Castor‑* (except those with System)
Content‑Base
Content‑Disposition
Content‑Encoding
Content‑Language
Content‑Length
Content‑Location
Content‑MD5
Content‑Type
Expires
Lifepoint
Policy‑* (except those with Evaluated[-Constrained])
X‑*‑Meta[‑*]

Tip

Add the preserve query argument to the COPY request to verify any custom metadata existing on the object is carried over to the copy. Include the header name with the new value on the request to overwrite an existing value. (v9.2)

See https://perifery.atlassian.net/wiki/spaces/public/pages/2443820996 for using these headers with COPY.

COPY for Named Objects

The syntax of a COPY request is similar to an empty PUT request on an alias object.

COPY /some/filename HTTP/1.1 
  Host: cluster.example.com  
  Content-Length: 0  
  x-xml-meta-data-color: blue  
  x-xml-meta-data-weight: 42  
  x-xml-meta-data: <size>large</size><color>blue</color><specialorder/>  
  lifepoint: [Sun, 06 Nov 2010 08:49:37 GMT] reps=3, deletable=no 

  lifepoint: [] delete

Renaming – Use the newname query argument, which provides a new name with the update request (PUT, COPY, APPEND), to rename a named object within the same bucket. Requests for the original name return an HTTP 404 Not Found and the prior search metadata is removed after renaming an object.

Behavior of COPY

Rewrites EC manifest. COPY rewrites the object manifest rather than creating a new object with new metadata if an erasure-coded object is modified by COPY. See https://perifery.atlassian.net/wiki/spaces/public/pages/2443811229.
Has no content body. The Content-Length header is optional. The value must be 0 because there is no content body for a COPY request if this header is included.
Replaces metadata headers. Additional headers (such as the two x-*-meta-* headers in the example and the lifepoint headers), replace all existing metadata in the original object. The one exception is the Content-Length header value continues to provide the original length of the content data.
Calculates and compares hashes.
- Non-EC object - Swarm recomputes the digest of the content data as it copies it and compares it with the provided MD5 hash if the client provides a Content-MD5 header with the COPY request. Similar to a WRITE, if the provided and calculated hashes do not match, the operation fails.
- EC object - The request calculates a new MD5 on non-EC objects. On an EC object, the gencontentmd5 query argument (or the deprecated Expect: Content-MD5 header) or content-md5 header is allowed if the existing object already has a content-md5 stored on it. Any new value must match the existing value.
Responses. Other aspects of the COPY method, including response codes, are the same as PUT. The COPY method returns a response after all data is copied and the object update is complete.

COPY for alias Objects

The UUID returned after a successful COPY is identical to the UUID supplied in the request, which is similar to a PUT or APPEND request.

The query argument alias=true is an optional acknowledgment the method is executed on an existing alias object. The object specified by the included UUID must be an alias object in Swarm.

Failure to perform a COPY on an alias object results in an HTTP 403 (Forbidden) response.

Normal Responses to COPY

A multipart COPY by part operates like a multipart write completion, sending back an HTTP 202 response code and keep-alive characters to prevent client timeouts. (v9.1.2)

See https://perifery.atlassian.net/wiki/spaces/public/pages/2443820996 for a list of response headers.

Error Responses to COPY

Swarm responds with 409 (Conflict) if executing the COPY method on an object in a domain but the domain does not exist or is not in the content cache on the node on which the request is directed.