GCS Path Encoding#

OpenDAL's GCS service implementation uses a custom percent-encoding scheme for object path segments in HTTP request URIs. The encoding logic is centralized in uri.rs and applied consistently inside the core request-builder functions in core.rs.

Encoding Scheme#

The GCS-specific encode set (GCS_PATH_ENCODE_SET) is derived from NON_ALPHANUMERIC, keeping only -, _, ., and * unencoded. This is more aggressive than the standard encodeURIComponent (which additionally preserves !, ~, ', (, )) and intentionally encodes / — because GCS treats slashes in the JSON/XML API as regular characters, not path delimiters. The public entry point is percent_encode_path.

Where Encoding Is Applied#

Encoding happens once, inside each core request builder, after prepending the configured root to the path. Examples from core.rs:

The presign (XML API) variants — gcs_get_object_xml_request, gcs_insert_object_xml_request, gcs_head_object_xml_request — use raw paths without calling percent_encode_path, relying on the HTTP client / signer to handle encoding for the XML API endpoint.

Known Bug: Double-Encoding in Writer (⚠ Open as of 2026-07-20)#

writer.rs currently pre-encodes paths before passing them to core request builders, causing double-encoding 1:

• write_once calls gcs_insert_object_request(&percent_encode_path(&self.path), …) — core then encodes again, so / → %2F → %252F 2
• initiate_part similarly pre-encodes before gcs_initiate_multipart_upload 3
• write_part and complete_part pass the raw path, making them inconsistent with write_once / initiate_part within the same multipart flow 4 5

Effect: Any object key containing / (e.g. dir/file.parquet) is stored under an incorrectly double-encoded name. A subsequent read using the original path encodes once (correctly) — but the object was stored under a doubly-encoded name — resulting in NotFound (404). This has been reproduced against fsouza/fake-gcs-server with the Python binding.

Fix direction (PR #7927, 1): Remove the percent_encode_path calls in writer.rs and pass &self.path directly to core request builders, matching the pattern used by write_part, complete_part, and the reader layer.

gcs_initiate_multipart_upload — Additional Gap#

gcs_initiate_multipart_upload builds its URL as {endpoint}/{bucket}/{p}?uploads without calling percent_encode_path 6. This means the multipart initiation uses a raw (unencoded) path while subsequent upload-part and complete calls use an encoded path. This is a separate gap from the writer double-encoding issue, and paths with special characters in multipart uploads via this function may behave differently from those in single-shot writes.

Key Files#