docs: Warn against collisions from custom upload IDs

See tus#1109

Author: Acconut

Diff for: docs/_advanced-topics/hooks.md

@@ -175,6 +175,15 @@ Below you can find an annotated, JSON-ish encoded example of a hook response:
         // path component according to RFC 3986 (https://datatracker.ietf.org/doc/html/rfc3986#section-3.3).
         // These are: A-Z a-z 0-9 - . _ ~ % ! $ ' ( ) * + , ; = / : @
         // In addition, IDs must not begin or end with a forward slash (/).
+        //
+        // When a custom upload ID is specified, it is the hook's responsibility to
+        // ensure that the upload ID will not cause collisions with resources from other
+        // uploads. Tusd does not check for collisions. Collisions happen frequently when
+        // the upload ID is mainly derived from the filename, which can be prevented by including
+        // a random part (e.g. a UUID) in the upload ID. In addition, be aware that some storage
+        // backends, such as the S3 store, save additional objects using `.info` and `.part`
+        // extensions. If you set a custom upload ID, ensure that this ID will also not collide
+        // with these additional objects.
         "ID": "my-custom-upload-id",
         // Set custom meta data that is saved with the upload and also accessible to
         // all future hooks. Note that this information is also visible to the client

Diff for: pkg/handler/datastore.go

@@ -54,6 +54,9 @@ func (f FileInfo) StopUpload(response HTTPResponse) {
 // can be done using the PreUploadCreateCallback to modify certain properties before
 // an upload is created. Properties which should not be modified (e.g. Size or Offset)
 // are intentionally left out here.
+//
+// Please also consult the documentation for the `ChangeFileInfo` property at
+// https://tus.github.io/tusd/advanced-topics/hooks/#hook-requests-and-responses.
 type FileInfoChanges struct {
 	// If ID is not empty, it will be passed to the data store, allowing
 	// hooks to influence the upload ID. Be aware that a data store is not required to

Diff for: pkg/handler/unrouted_handler.go

@@ -1545,7 +1545,7 @@ func getRequestId(r *http.Request) string {
 	return reqId
 }
 
-// validateUploadId checks whether an ID included in a FileInfoChange struct is allowed.
+// validateUploadId checks whether an ID included in a FileInfoChanges struct is allowed.
 func validateUploadId(newId string) error {
 	if newId == "" {
 		// An empty ID from FileInfoChanges is allowed. The store will then