Implement GSP-134 Write Behavior Consistency (#656)

definitions/operations.toml

@@ -2,9 +2,17 @@
 description = "is the interface for Append related operations."
 
 [appender.op.create_append]
-description = "will create an append object."
 params = ["path"]
 results = ["o"]
+description = """
+will create an append object.
+
+## Behavior
+
+- CreateAppend SHOULD create an appendable object with position 0 and size 0.
+- CreateAppend SHOULD NOT return an error as the object exist.
+  - Service SHOULD check and delete the object if exists.
+"""
 
 [appender.op.write_append]
 description = "will append content to an append object."
@@ -21,9 +29,16 @@ object_mode = "append"
 description = "is the interface for Block related operations."
 
 [blocker.op.create_block]
-description = "will create a new block object."
 params = ["path"]
 results = ["o"]
+description = """
+will create a new block object.
+
+## Behavior
+- CreateBlock SHOULD NOT return an error as the object exist.
+  - Service that has native support for `overwrite` doesn't NEED to check the object exists or not.
+  - Service that doesn't have native support for `overwrite` SHOULD check and delete the object if exists.
+"""
 
 [blocker.op.write_block]
 description = "will write content to a block."
@@ -46,8 +61,21 @@ object_mode = "block"
 description = "is the interface for Copy."
 
 [copier.op.copy]
-description = "will copy an Object or multiple object in the service."
 params = ["src", "dst"]
+description = """
+will copy an Object or multiple object in the service.
+
+## Behavior
+
+- Copy only copy one and only one object.
+  - Service DON'T NEED to support copy a non-empty directory or copy files recursively.
+  - User NEED to implement copy a non-empty directory and copy recursively by themself.
+  - Copy a file to a directory SHOULD return `ErrObjectModeInvalid`.
+- Copy SHOULD NOT return an error as dst object exists.
+  - Service that has native support for `overwrite` doesn't NEED to check the dst object exists or not.
+  - Service that doesn't have native support for `overwrite` SHOULD check and delete the dst object if exists.
+- A successful copy opration should be complete, which means the dst object's content and metadata should be the same as src object.
+"""
 
 [direr]
 description = "is the interface for Directory."
@@ -61,23 +89,49 @@ results = ["o"]
 description = "is the interface for Fetch."
 
 [fetcher.op.fetch]
-description = "will fetch from a given url to path."
 params = ["path", "url"]
+description = """
+will fetch from a given url to path.
+
+## Behavior
+
+- Fetch SHOULD NOT return an error as the object exists.
+- A successful fetch operation should be complete, which means the object's content and metadata should be the same as requiring from the url.
+"""
 
 [mover]
 description = "is the interface for Move."
 
 [mover.op.move]
-description = "will move an object in the service."
 params = ["src", "dst"]
+description = """
+will move an object in the service.
+
+## Behavior
+
+- Move only move one and only one object.
+  - Service DON'T NEED to support move a non-empty directory.
+  - User NEED to implement move a non-empty directory by themself.
+  - Move a file to a directory SHOULD return `ErrObjectModeInvalid`.
+- Move SHOULD NOT return an error as dst object exists.
+  - Service that has native support for `overwrite` doesn't NEED to check the dst object exists or not.
+  - Service that doesn't have native support for `overwrite` SHOULD check and delete the dst object if exists.
+- A successful move operation SHOULD be complete, which means the dst object's content and metadata should be the same as src object.
+"""
 
 [multiparter]
 description = "is the interface for Multipart related operations."
 
 [multiparter.op.create_multipart]
-description = "will create a new multipart."
 params = ["path"]
 results = ["o"]
+description = """
+will create a new multipart.
+
+## Behavior
+
+- CreateMultipart SHOULD NOT return an error as the object exists.
+"""
 
 [multiparter.op.write_multipart]
 description = "will write content to a multipart."
@@ -100,9 +154,15 @@ object_mode = "part"
 description = "is the interface for Page related operations which support random write."
 
 [pager.op.create_page]
-description = "will create a new page object."
 params = ["path"]
 results = ["o"]
+description = """
+will create a new page object.
+
+## Behavior
+
+- CreatePage SHOULD NOT return an error as the object exists.
+"""
 
 [pager.op.write_page]
 description = "will write content to specific offset."
@@ -205,7 +265,16 @@ will stat a path to get info of an object.
 """
 
 [storager.op.write]
-description = "will write data into a file."
 params = ["path", "r", "size"]
 pairs = ["io_callback"]
 results = ["n"]
+description = """
+will write data into a file.
+
+## Behavior
+
+- Write SHOULD NOT return an error as the object exist.
+  - Service that has native support for `overwrite` doesn't NEED to check the object exists or not.
+  - Service that doesn't have native support for `overwrite` SHOULD check and delete the object if exists.
+- A successful write operation SHOULD be complete, which means the object's content and metadata should be the same as specified in write request.
+"""