1 WRITE for Named Objects
- 1.1 Using PUT Create for Named Objects
- 1.2 Preventing Overwriting: If-None-Match
2 WRITE for Unnamed Objects
3 WRITE for alias Objects
4 WRITE for Erasure-Coded Objects
5 WRITE for Large Files (Expect: 100-Continue)

This section provides general information about SCSP WRITE that applies to both named and unnamed objects.

WRITE is a request to the storage cluster to create a new object. The WRITE request is formatted as an HTTP request using the POST method.

SCSP Method	HTTP Method	RFC 7231 Section

SCSP Method	HTTP Method	RFC 7231 Section
SCSP WRITE	POST	4.3.3

Write for Contexts

The Swarm setting scsp.requireExplicitContextCreate protects content-bearing objects from being created erroneously as contexts (buckets or domains). With this setting enabled, Swarm does not create a context object unless it includes the required header: Content-type: application/castorcontext. (v9.1)

S3 Compatibility

The Swarm setting scsp.autoContentMD5Computation improves S3 compatibility by automating Content-MD5 hashing. the gencontentmd5 query argument or the deprecated Expect: Content-MD5 header does not need to be included on writes (although a separate Content-MD5 header may want to be supplied for content integrity checking). This setting is ignored wherever it is invalid, such as on a multipart initiate/complete or an EC APPEND. (v9.1)

WRITE for Named Objects

The existing object is overwritten with a new version if performing a WRITE of a named object that already exists.

WRITE that overwrites object

POST /bucket/photo.jpg HTTP/1.1
  Host: cluster.example.com
  User-Agent: Swarm Client/0.1
  Content-Length: 43402
  Expect: 100-continue
  Content-Type: image/jpeg 
  Content-Language: en/us, x-pig-latin 
  Content-Version: 42
  CRLF
  [ content ]

Include the If-None-Match: * request header to prevent overwriting an existing object.

Swarm WRITEs the named object if the named object does not exist.
Swarm responds with an HTTP 412 Precondition Fail error if the named object exists.

WRITE that prevents overwriting

POST /bucket/photo.jpg HTTP/1.1
  If-None-Match: *
  Host: cluster.example.com
  User-Agent: Swarm Client/0.1
  Content-Length: 43402
  Expect: 100-continue
  Content-Type: image/jpeg
  Content-Language: en/us, x-pig-latin
  Content-Version: 42 
  CRLF 
  [ content ]

Using PUT Create for Named Objects

Add the scsp.allowPutCreate=True to the configuration parameters to configure Swarm to allow using the HTTP PUT operation to create new named objects. The putcreate query argument can also enable it.

Exception

Although domains and buckets are named, Swarm processes all PUT requests on these objects as updates, regardless of the setting.

Swarm fails the request with a 400 Bad Request error if the putcreate=yesSCSP Query Argumentsquery argument is used on a domain or bucket.
Swarm silently ignores it and processes the request as an ordinary PUT if the scsp.allowPutCreate parameter is enabled.

Preventing Overwriting: If-None-Match

In contrast to an unnamed object, the existing object is overwritten with a new version if performing a WRITE of a named object that already exists. Include the If-None-Match: * request header to prevent overwriting an existing object.

Swarm WRITEs the named object if the named object does not exist.
Swarm responds with an HTTP 412 Precondition Fail error if the named object exists.

WRITE for Unnamed Objects

Swarm makes no assumptions about User-Agent (except it is an HTTP/1.1 client). The Host header must conform to the requirements of Section 14.23 of the HTTP/1.1 spec.

WRITE unnamed to host domain

POST / HTTP/1.1 
  Host: cluster.example.com 
  User-Agent:Swarm Client/0.1 
  Content-Length: 43402 
  Expect: 100-continue
  Content-Type: image/jpeg
  Content-Language: en/us, x-pig-latin
  Content-Version: 42 
  CRLF 
  [ content ]

A new object is created and a new UUID is returned if performing a WRITE of an unnamed object. A new object is created and a new alias UUID is returned if performing a WRITE of an alias object.

See https://perifery.atlassian.net/wiki/spaces/public/pages/2443821691.

WRITE for alias Objects

Add alias=yes to create alias objects:

WRITE for alias object

WRITE for Erasure-Coded Objects

A new object written to the storage cluster is erasure-coded if it meets the EC criteria language.

See https://perifery.atlassian.net/wiki/spaces/public/pages/2443811229.

WRITE for Large Files (Expect: 100-Continue)

The Expect: 100-continue header tells the server the client waits after sending the header lines and before sending the content in the message body. The Swarm server can respond with a redirect or an error response.

The server returns an HTTP 100 Continue response, telling the client to transmit the entity body if the server is ready to store the contents. The client needs to wait for a 100 Continue response from the server before proceeding to send the data.
The server sends an HTTP 413 Request entity too large error response and closes the connection if the server is not ready.

Swarm allows the client to omit the Expect: 100-continue header, sending all content at once. The server reads and discards all data if it must respond with a redirect or error. Swarm logs a warning for WRITE messages that include more than 65536 bytes:

Error if Expect header is missing

The cluster returns an HTTP 507 Insufficient Storage error if any node in the cluster does not have enough space to write the object.