Skip to content

feat(ExternalStorage) Allow the use of 'prefix' in S3 buckets#61585

Open
mbartsch wants to merge 2 commits into
nextcloud:masterfrom
mbartsch:feature/s3-external-prefix
Open

feat(ExternalStorage) Allow the use of 'prefix' in S3 buckets#61585
mbartsch wants to merge 2 commits into
nextcloud:masterfrom
mbartsch:feature/s3-external-prefix

Conversation

@mbartsch

@mbartsch mbartsch commented Jun 25, 2026

Copy link
Copy Markdown

Summary

Adds an optional Object key prefix parameter to the S3-Compatible Object Storage external storage backend.

This allows scoping a mount to a sub-path within a shared bucket rather than requiring exclusive use of the entire bucket. For example, setting the
prefix to nextcloud/$user/ will store each user's files under their own namespace within the bucket, with $user being substituted automatically at
mount time.

What changed:

  • Backend/AmazonS3.php: new optional prefix field exposed in the admin UI
  • Storage/AmazonS3.php: prefix is parsed and normalized in the constructor (leading slashes stripped, trailing slash enforced), then applied
    transparently to all S3 key operations (read, write, delete, list, copy, presigned URLs). Keys returned from S3 listing responses have the prefix
    stripped before being stored in the in-memory cache or yielded as directory entries. The storage ID includes the prefix so two mounts to the same
    bucket with different prefixes are treated as distinct storages.

Variable substitution: $user (and any other registered placeholder) works in the prefix field automatically, since all backend options pass through
the existing applyConfigHandlers() pipeline before the storage is constructed.

TODO

  • Add unit tests for addPrefix / stripPrefix helpers and constructor normalization
  • Add integration test covering mount with a prefix set

Checklist

AI (if applicable)

  • The content of this PR was partly or fully generated using AI

Assisted-by: CloudeCode:claude-sonnet-4-6

@mbartsch
mbartsch force-pushed the feature/s3-external-prefix branch from 6a2538d to 7e55e24 Compare June 25, 2026 08:27
@mbartsch
mbartsch marked this pull request as ready for review June 25, 2026 09:12
@mbartsch
mbartsch requested a review from a team as a code owner June 25, 2026 09:12
@mbartsch
mbartsch requested review from ArtificialOwl, come-nc, provokateurin and salmart-dev and removed request for a team June 25, 2026 09:12
@susnux susnux added this to the Nextcloud 35 milestone Jun 25, 2026
@susnux

susnux commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

Thank you for your pull request!
Please add the disclosure to your commits as per policy:
https://github.com/nextcloud/.github/blob/master/AI_POLICY.md#disclosure

Also you need to use conventional commit messages (e.g. feat(...): ...):
https://www.conventionalcommits.org/en/v1.0.0/

@susnux susnux added the community pull requests from community label Jun 25, 2026
@mbartsch mbartsch changed the title Allow the use of 'prefix' in S3 buckets feat(ExternalStorage) Allow the use of 'prefix' in S3 buckets Jun 25, 2026
@mbartsch

Copy link
Copy Markdown
Author

Hope now is OK, if not, please let me know.

@CarlSchwan
CarlSchwan force-pushed the feature/s3-external-prefix branch from b426fe4 to cc7a490 Compare June 30, 2026 13:34
Signed-off-by: Marcelo H. Bartsch <marcelo@bartsch.cl>
Signed-off-by: Carl Schwan <carlschwan@kde.org>
@CarlSchwan
CarlSchwan force-pushed the feature/s3-external-prefix branch from cc7a490 to c5e4cce Compare June 30, 2026 13:35
@github-actions

Copy link
Copy Markdown
Contributor

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!

(If you believe you should not receive this message, you can add yourself to the blocklist.)

Comment on lines 274 to +277
if ($path !== null) {
$params['Prefix'] = $path . '/';
$params['Prefix'] = $this->addPrefix($path . '/');
} elseif ($this->prefix !== '') {
$params['Prefix'] = $this->prefix;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can be simplified by doing $path = $this->addPrefix($path . '/'); above the if

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants