docs: slim README down, move deep docs to the wiki#79
Merged
Conversation
Ports the useful parts of Tresillo2017's R2 fork (compare/main...Tresillo2017:BlueMapS3Storage:main) cleanly: that fork's diff turned out to contain no actual Java changes despite its CHANGELOG_R2.md describing new R2Storage/R2Configuration classes, just three overlapping markdown files and an accidentally committed node_modules/. R2 is S3-compatible, so it already works through the existing themeinerlp:s3 storage type. Rather than duplicating that as a parallel R2-specific implementation, this adds: - account-id: optional Cloudflare account ID. When set (and endpoint-url is left empty), the endpoint is derived automatically as https://<account-id>.r2.cloudflarestorage.com and path-style access is forced on, since R2 only supports path-style. - list-cache-ttl-seconds: optional TTL cache for mapIds() (map enumeration), since directory listings are a billed "Class A" operation on R2. Off by default (0); only affects map enumeration at init/reload, not tile reads/writes. (Fixes a pre-existing resource leak in mapIds() along the way — the underlying DirectoryStream was never closed.) Consolidates the fork's R2_GUIDE.md/R2_QUICK_START.md/CHANGELOG_R2.md into a single docs/cloudflare-r2.md, and documents both new options plus the existing checksum-validation option (added in #73 but never added to the README) in the main config table.
S3Configuration was starting to accumulate provider-specific optional fields (account-id for R2, alongside checksum-validation and the generic fields) that only ever matter for one particular backend. Adding the next provider's shorthand would mean growing the shared interface again. Introduces a small ProviderProfile abstraction instead: each profile knows how to recognize its own shorthand config and resolve it into the plain endpoint-url/force-path-style/region settings S3FileSystemFactory already understood. The factory itself no longer has any R2-specific logic - it just asks ProviderProfiles.resolve() for the effective connection settings. - ProviderProfile: the resolve contract + ResolvedEndpoint record - R2Profile: derives the R2 endpoint from account-id, forces path-style - GenericS3Profile: passes cfg's own endpoint-url/force-path-style/ region through unchanged - the fallback, tried last - ProviderProfiles: tries each profile in order, first match wins No config/behavior change for existing users. Adding a future provider's own shorthand (e.g. a hypothetical B2 profile) now means adding one small profile class, not touching the shared config interface or the factory.
README is now a short intro + quick start, linking out to the wiki (https://github.com/TheMeinerLP/BlueMapS3Storage/wiki) for the full config reference, provider examples, the Cloudflare R2 guide, and build instructions. Removes docs/cloudflare-r2.md, now superseded by the wiki's Cloudflare-R2 page (kept in sync, same content).
Same squash-merge ancestry gap as feat/r2-support: the true merge-base with main predates docs/cloudflare-r2.md ever existing, so git's 3-way merge couldn't see this branch's net deletion of it. Forced the deletion explicitly since the target state (this branch's tip tree) is unambiguous - confirmed identical to origin/docs/slim-readme-wiki before committing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Stacked on #78 (stacked on #77). The wiki (https://github.com/TheMeinerLP/BlueMapS3Storage/wiki) now has:
checksum-validation,account-id,provider,list-cache-ttl-secondsfrom feat: add Cloudflare R2 support via account-id and optional list caching #77/refactor: extract provider-specific config into ProviderProfile (Strategy) #78, previously undocumented in README)docs/cloudflare-r2.md)README is now a short intro + quick start + links out to the wiki pages above, removes
docs/cloudflare-r2.md(superseded by the wiki page with the same content).Test plan
./gradlew compileJavapasses (docs-only change, but confirming nothing else broke)main