Skip to content

docs: document the cloud files contract and how to change it - #142

Merged
omarghatasheh merged 1 commit into
mainfrom
muhannad/cloudfiles-contract-docs
Nov 19, 2026
Merged

omarghatasheh merged 1 commit into
mainfrom
muhannad/cloudfiles-contract-docs

Conversation

@mmalkhatib

Copy link
Copy Markdown
Contributor

Comments and README only; no API change.

  • XML docs on ICloudFilesService, WriteFileSettings, CloudFileInfo, RemoteBlob, WriteWrapper, CloudFilesOptions: what each member does and where the providers differ (metadata keys, missing-key results and exceptions, signed-URL cost, ListAsync paging before CloudFiles 10.0.4, OpenWrite S3-only, Public/Metadata not honoured everywhere). Most summaries were empty or said "Method to read a file".
  • The interface's remarks state the evolution rule: applications implement ICloudFilesService too, so capabilities are added as separate interfaces registered beside it, as ICloudFilesLifecycle is.
  • README: a cloud files section linking to the CloudFiles provider-behaviour and contract-evolution docs (fix(s3, oc): ListAsync returns every page; document provider behaviour SW-CloudFiles#116), and a fixed CloudFiles repository link.

Builds clean.

XML docs on ICloudFilesService, WriteFileSettings, CloudFileInfo, RemoteBlob,
WriteWrapper and CloudFilesOptions replace the empty or vague summaries: what each
member does, where providers differ (metadata keys, missing-key results, signed-URL
cost, ListAsync paging), and that new capabilities go in separate interfaces
because applications implement ICloudFilesService too. README gains a cloud files
section; its CloudFiles link pointed at the wrong repository.

Comments only; no API change.
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Summary

What changed

This change is documentation only. It has 7 files changed, with 180 lines added and 45 removed.

  • ICloudFilesService.cs: Replaces the XML documentation for each member. Documents the object-storage model, provider-specific behavior, and limitations. Adds a warning that adding or changing interface members breaks applications that implement the interface. Recommends separate interfaces for new capabilities.
  • CloudFileInfo.cs: Documents Key, Size, and Signature. Signature is an opaque change marker. Compare its values only for equality.
  • CloudFilesOptions.cs: Documents the shared settings and the CloudFiles configuration section. Documents the Driver property. Providers do not read it.
  • WriteFileSettings.cs: Documents key format, lifecycle prefixes, default content types, and provider handling of public access and stream closure. Documents metadata limits and key casing.
  • WriteWrapper.cs: Documents the streamed-upload sequence, S3-only support, and use of obsolete HttpWebRequest. Recommends ICloudFilesService.WriteAsync for new code. Removes a UTF-8 BOM from the using System; line.
  • RemoteBlob.cs: Documents RemoteBlob, Location, Size, and MimeType.
  • README.md: Adds a CloudFiles contract section. Corrects the CloudFiles repository link to SW-CloudFiles.

Risk level: risk:low

No runtime code or public signatures change. The PR states that the API does not change.

Security-sensitive areas

  • The docs state that Public and Metadata are not honored by every provider. Applications that depend on public access or metadata for access control must check provider behavior. The docs do not add a code-level control.
  • The docs note signed-URL cost. This affects operational cost, not access control.

Test coverage impact

No tests change. The PR author reports a clean build. This review did not build the project or run tests, so that result is not verified here.

Deployment, migration, and rollback

  • No deployment or migration steps are needed.
  • Rollback is a documentation revert with no runtime effect.
  • Consumers that read the XML documentation output see new text. No consumer behavior changes.

Review notes

  • Confirm that the documented provider differences match the current SW-CloudFiles provider behavior. Review links to SW-CloudFiles PR #116 for the provider details.
  • Confirm that the BOM removal in WriteWrapper.cs does not affect other tooling.

The README and CloudFiles XML documentation now describe the service contract, provider-specific operation behavior, shared settings and models, and contract evolution. The SimplyWorks.CloudFiles repository link is updated. No runtime behavior or public signatures change.

Changes: CloudFiles documentation

Layer / File(s) Summary
Contract overview and shared models
README.md, SW.PrimitiveTypes/Contracts/CloudFiles/ICloudFilesService.cs, SW.PrimitiveTypes/Contracts/CloudFiles/CloudFilesOptions.cs, SW.PrimitiveTypes/Contracts/CloudFiles/CloudFileInfo.cs
The README describes the CloudFiles contract and its evolution. XML comments describe the service contract, configuration options, and CloudFileInfo. The SimplyWorks.CloudFiles repository link now points to SW-CloudFiles.
Service operation documentation
SW.PrimitiveTypes/Contracts/CloudFiles/ICloudFilesService.cs
XML comments describe provider-specific behavior and constraints for write, URL, stream, list, metadata, and delete operations.
Write settings and result documentation
SW.PrimitiveTypes/Contracts/CloudFiles/WriteFileSettings.cs, SW.PrimitiveTypes/Patterns/ValueObjects/RemoteBlob.cs, SW.PrimitiveTypes/Contracts/CloudFiles/WriteWrapper.cs
XML comments describe write settings, RemoteBlob properties, and the S3-only WriteWrapper workflow.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Suggested labels: risk:low

Suggested reviewers: samerzughul, awajan

Merge Risk: Minimal · up to 1fb86

This is a documentation-only change with no runtime impact. It is safe to merge. Provider-specific statements, such as how public access behaves on ACL-disabled S3 buckets, could not be checked against the external provider code.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title "docs: document the cloud files contract and how to change it" matches the main change. The PR adds XML documentation to CloudFiles contract types and a README section on the contract and it…
Description check Passed The description lists the XML documentation added to the CloudFiles contract types, the README section, the interface evolution rule, and the fixed repository link. It states the change is comments an…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title "docs: document the cloud files contract and how to change it" matches the main change. The PR adds XML documentation to CloudFiles contract types and a README section on the contract and its evolution rules. The title is concise and specific.

Full details: Description check

Explanation

The description lists the XML documentation added to the CloudFiles contract types, the README section, the interface evolution rule, and the fixed repository link. It states the change is comments and README only with no API change. It is directly related to the changeset.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Central YAML; Path: .coderabbit.yaml
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 671cbddf-f77d-406c-b40f-19f83329b68c
Commits

Reviewing files that changed from the base of the PR and between 88803db and 1fb86e2.

Files selected for processing: 7

  • README.md
  • SW.PrimitiveTypes/Contracts/CloudFiles/CloudFileInfo.cs
  • SW.PrimitiveTypes/Contracts/CloudFiles/CloudFilesOptions.cs
  • SW.PrimitiveTypes/Contracts/CloudFiles/ICloudFilesService.cs
  • SW.PrimitiveTypes/Contracts/CloudFiles/WriteFileSettings.cs
  • SW.PrimitiveTypes/Contracts/CloudFiles/WriteWrapper.cs
  • SW.PrimitiveTypes/Patterns/ValueObjects/RemoteBlob.cs

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Recent review details

Context from checks skipped due to timeout: 1

  • GitHub Check: CodeRabbit
Additional comments: 1

SW.PrimitiveTypes/Contracts/CloudFiles/WriteFileSettings.cs: 1

33-33: Functional Correctness

The S3 claim cannot be decided from this checkout. Whether the S3 write path sends a public-read ACL to a Bucket owner enforced bucket is decided in the SW-CloudFiles S3 provider. That implementation is not in the permitted repositories. The contract documentation in this repository does not show it.

@omarghatasheh
omarghatasheh merged commit 2f0ec93 into main Nov 19, 2026
5 checks passed
@omarghatasheh
omarghatasheh deleted the muhannad/cloudfiles-contract-docs branch November 19, 2026 16:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants