MSC2246 Asynchronous uploads updates from Travis's review

proposals/2246-asynchronous-uploads.md

@@ -16,7 +16,7 @@ transfers, as requested in [matrix-spec#432].
 The proposal adds two new endpoints to the content repository API and modifies
 the download and thumbnail endpoints.
 
-#### `POST /_matrix/media/v3/create`
+#### `POST /_matrix/media/v1/create`
 Create a new MXC URI without content. Like `/upload`, this endpoint requires
 auth and returns the `content_uri` that can be used in events.
 
@@ -43,31 +43,35 @@ lots of unused ids.
 ```
 
 #### `PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`
-Upload content to a MXC URI that was created earlier. If the endpoint is called
-with a media ID that already has content, the request should be rejected with
-the error code `M_CANNOT_OVERWRITE_MEDIA` and HTTP status code 409. The endpoint
-should also reject upload requests from users other than the user who created
-the media ID. This endpoint requires auth.
+Upload content to a MXC URI that was created earlier. This endpoint requires
+auth. If the upload is successful, an empty JSON object and status code 200 is
+returned.
 
-If the upload is successful, an empty JSON object and status code 200 is
-returned. If the serverName/mediaId combination is not known or not local, an
-`M_NOT_FOUND` error is returned. For other errors, such as file size, file type
-or user quota errors, the normal `/upload` rules apply.
+If the endpoint is called with a media ID that already has content, the request
+should be rejected with the error code `M_CANNOT_OVERWRITE_MEDIA` and HTTP
+status code 409.
 
-The client should include a `Content-Length` header to ensure the server knows
-if the file was uploaded entirely. If the server receives a different amount of
-data than specified in the header, the upload must fail.
+If the upload request comes from a user other than the one who created the media
+ID, the request should be rejected with an `M_FORBIDDEN` error.
+
+If the serverName/mediaId combination is not known, not local, or expired, an
+`M_NOT_FOUND` error is returned.
+
+For other errors, such as file size, file type or user quota errors, the normal
+`/upload` rules apply.
 
 #### Changes to the `/download` and `/thumbnail` endpoints
-A new query parameter, `max_stall_ms` is added to the endpoints that can
+A new query parameter, `timeout_ms` is added to the endpoints that can
 download media. It's an integer that specifies the maximum number of
 milliseconds that the client is willing to wait to start receiving data.
-The default value is 20000 (20 seconds).
+The default value is 20000 (20 seconds). The server can and should impose a
+maximum value for this parameter.
+
+If the media is available immediately (for example in the case of a
+non-asynchronous upload), the server should ignore this parameter.
 
 If the data is not available before the specified time is up, the content
-repository returns a `M_NOT_YET_UPLOADED` error with a HTTP 404 status code.
-The error may include an additional `retry_after_ms` field to suggest when the
-client should try again.
+repository returns a `M_NOT_YET_UPLOADED` error with a HTTP 504 status code.
 
 For the `/download` endpoint, the server could also stream data directly as it
 is being uploaded. However, streaming creates several implementation and spec
@@ -90,7 +94,7 @@ use `fi.mau.msc2246` as a prefix and as an `unstable_features` flag in the
 
 * `POST /_matrix/media/unstable/fi.mau.msc2246/create`
 * `PUT /_matrix/media/unstable/fi.mau.msc2246/upload/{serverName}/{mediaId}`
-* `?fi.mau.msc2246.max_stall_ms`
+* `?fi.mau.msc2246.timeout_ms`
 * `FI.MAU.MSC2246_NOT_YET_UPLOADED`
 * `FI.MAU.MSC2246_CANNOT_OVERWRITE_MEDIA`