Skip to content

feat(services/sharepoint): add SharePoint document library service - #8313

Open
DavidIsaacBPS wants to merge 7 commits into
apache:mainfrom
BPS-Consulting:david/enh/add-sharepoint-provider
Open

DavidIsaacBPS wants to merge 7 commits into
apache:mainfrom
BPS-Consulting:david/enh/add-sharepoint-provider

Conversation

@DavidIsaacBPS

Copy link
Copy Markdown

Closes #5409

Rationale for this change

Introduces opendal-service-sharepoint, enabling access to Microsoft SharePoint document libraries. This implementation closely follows the existing OneDrive service, adapting for SharePoint's unique addressing and authentication requirements. The README has been updated to include SharePoint in the service table. No user-facing changes or breaking changes are introduced: some OneDrive components are cloned (rather than modified) for safety. A more limited follow-on PR can merge common components after the code is proven in the field.

What changes are included in this PR?

Adds opendal-service-sharepoint, a new Microsoft Graph–backed service for SharePoint document libraries, following the design of opendal-service-onedrive (path addressing, @odata.nextLink paging, chunked upload sessions, async copy monitoring, HTTP status → ErrorKind mapping) with three key differences:

Addressing: a configurable folder_url is resolved once via Graph's /shares endpoint into a drive id + item id, since SharePoint has no /me/drive/root equivalent.
Listing: child paths are built from the listed directory + item name (rather than parentReference.path, which is relative to the drive root, not the anchor).
Auth: delegated-only, with configurable tenant_id (default common) and Sites.ReadWrite.All scope.
Also includes:

README/service-table and website/data/services.json entries, plus the SharePoint logo asset.
examples/connection_check.rs, an interactive device-code sign-in example exercising a full round trip.
sharepoint added to the python/java binding-generator exclusion lists (bindings not wired up yet).

Are there any user-facing changes?

Yes — a new sharepoint service is now available to configure and use like any other OpenDAL service. Changes for the README are included.

Breaking changes

AI Usage Statement

Harness: Claude Code
Model: Claude Opus 5 / Claude Sonnet 5
Effort: n/a (default)
Role: Implemented the SharePoint service, wrote documentation and example code, and addressed code review findings under human direction and review.

Testing

Built and run on Windows 11 with MS 365 SharePoint target. In use for the last two months without issue.

DavidIsaacBPS and others added 4 commits August 10, 2026 18:17
Add `opendal-service-sharepoint`, a Microsoft Graph backed service for
SharePoint document libraries. SharePoint exposes the same `driveItem`
API as OneDrive, so the crate follows `opendal-service-onedrive` closely:
path addressing, `@odata.nextLink` paging, `createUploadSession` with
unsigned `Content-Range` chunk PUTs, the async copy monitor loop, and the
HTTP status to `ErrorKind` mapping all carry over. `onedrive` is unchanged.

Three things differ and drive the design:

Addressing. OneDrive hardcodes `/me/drive/root`, which has no SharePoint
equivalent. Instead, `folder_url` names the anchor folder as it appears in
the browser, and is resolved once through Graph's `/shares` endpoint into
a drive id plus item id. Resolving via `/shares` avoids having to guess
where the site path ends and the library path begins, which is not
decidable from the URL alone once subsites or managed paths are involved.
Resolution is lazy through `mea::once::OnceCell` because `Builder::build`
is synchronous and has no `OperationContext`.

Anchoring on an immutable item id, then addressing leaves by path relative
to it, is the hybrid Graph documents. Renaming the site, the library, or
the anchor folder does not invalidate a configured operator, while paths
below it stay compatible with OpenDAL's path-keyed `Service` contract.

Listing. `parentReference.path` is relative to the drive root, not to the
anchor, so it cannot be used the way `onedrive` uses it. Child paths are
built from the listed directory plus the item name instead, which is
correct for any anchor depth.

Auth. Delegated only, with a configurable `tenant_id` (default `common`)
and scope `offline_access Sites.ReadWrite.All`. Writes are therefore
attributed to the signed-in user rather than to the application.

Name validation is deliberately left to the caller. SharePoint reserves
`#` and `%` on top of the OneDrive set, but both are tenant-configurable,
and `ErrorKind` has no variant for an invalid path. Paths are passed
through and the service surfaces Graph's rejection, matching every other
service. Encoding is handled by the existing `percent_encode_path`.

`stat_with_version`, `list_with_versions`, and the `if_match` /
`if_none_match` capabilities are not declared yet. They depend on library
versioning settings and on `eTag`, which covers metadata as well as
content on SharePoint. The request builders already honor the arguments,
so each is a one-line change once behavior tests confirm it.

Bindings are not wired up, so `sharepoint` is added to the python and java
generator exclusion lists to keep generated binding code consistent.

Add `examples/connection_check.rs`, an interactive device-code sign-in that
exercises a full round trip against a real document library.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Add sharepoint to the Cloud SaaS group alongside the other Microsoft 365
services, with the SharePoint (2019-2025) logo.

The logo is the Wikimedia Commons SVG with its Adobe Illustrator preamble
removed: the XML declaration, the DOCTYPE and its seven custom ENTITY
declarations, the Adobe namespace attributes that referenced those
entities, and the sfw metadata block. Entity-bearing SVGs are rejected by
some sanitizers, and the namespace attributes could not outlive the
entities they resolved against. The artwork is unchanged, keeping the same
viewBox, three circles, six paths, and the SVGID_1_ gradient.

The landing page showcase in website/src/components/landing/data.js is
left alone; it is a curated selection rather than a complete list.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Format, plus three defects found reviewing the service against the
project's CI gates.

cargo fmt. The code-format job runs `cargo fmt -- --check` across the
workspace and was failing on a 172-line diff spanning core.rs,
graph_model.rs, writer.rs, and the example. Formatting only.

sharepoint_list_versions checked no HTTP status. It deserialized the body
directly, so an error response was parsed as a versions list and surfaced
as a confusing JSON error rather than a mapped ErrorKind. Every other
method in the module checks status first.

The lister asked for versions on directories. A folder has no versions, so
that spent a request per folder to receive an error, which then hit the
missing status check above. Versions are now requested for files only. The
trailing slash is appended when building the entry path rather than
mutating the path beforehand, so the versions call receives a clean path.

The anchor-vs-path branch for `children` URLs was duplicated in
sharepoint_list_request and sharepoint_create_dir, and only the list copy
had tests. That is backwards: create_dir is where OneDrive gets this wrong,
building `root:/children` for the root case. Extracted into
sharepoint_children_url so both callers cannot drift, and added three tests
pinning the create_dir shapes for a top-level folder, a nested folder, and
a custom operator root.

Also drop webUrl from the anchor $select and struct; it was requested but
never read.

Not changed, and worth a maintainer's view: `op.list_with(path)
.recursive(true)` returns a single level silently, because the correctness
check layer validates recursion for delete but not list, and no core-level
emulation exists for hierarchical services. This matches onedrive, gdrive,
dropbox, and koofr, so it is a framework-level gap rather than something
this service should work around.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…elds

Items at the document library root omit `eTag`, and the `parentReference`
of the root's direct children omits both `path` and `id` — so deserializing
either as a required String failed as soon as an operator was anchored at
the library root rather than at a subfolder.

Make all three optional. `path`/`id` are never read (only `drive_id` is);
they exist only to round-trip through `SharePointPatchRequestBody` for copy
and rename, which sends its own synthetic values, so `skip_serializing_if`
leaves the outgoing payload unchanged. `eTag` now sets metadata only when
present.

Covered by a new `graph_model` test listing a root child that has neither
field.
@DavidIsaacBPS DavidIsaacBPS changed the title Add SharePoint document library service feat(services/SharePoint): add SharePoint document library service Sep 20, 2026
@DavidIsaacBPS DavidIsaacBPS changed the title feat(services/SharePoint): add SharePoint document library service feat(services/sharepoint): add SharePoint document library service Sep 20, 2026
@DavidIsaacBPS

DavidIsaacBPS commented Sep 20, 2026 •

Copy link
Copy Markdown
Author

Please consider fixing the PR classifier label.py, which is susceptible to failure for a large PR like this one. Be advised:

The immediate repository-side fix would be to make the classifier robust to truncation, for example by:

  • Reducing the prompt/input size for large PRs.
  • Retrying when finish_reason != "stop".
  • Falling back to a deterministic classification or leaving the PR unlabeled rather than failing the entire check.
    The underlying issue is a weakness in the new labeling automation, not a SharePoint service implementation failure.

For example:

+INDETERMINATE = {"category": "indeterminate", "components": [], "breaking_change": False}
 def classify(body):
...
+    print(json.dumps({"model": MODEL, "usage": result.get("usage")}))
     if choice["finish_reason"] != "stop":
-        raise ValueError("Incomplete model output")
-    print(json.dumps({"model": MODEL, "usage": result.get("usage")}))
-    return json.loads(choice["message"]["content"])
+        print(json.dumps({"classification": "indeterminate", "finish_reason": choice["finish_reason"]}))
+        return dict(INDETERMINATE if "breaking_change" in body else {**INDETERMINATE, "breaking_change": None})
+    return json.loads(choice["message"]["content"])

@erickguan erickguan left a comment

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 looks good to have though these API implementation look just like onedrive. Is there opportunity to use the same backend? e.g.,

  1. Add sharepoint_graph_model.rs and core in onedrive
  2. Initialize implementation according to sites.

This might be impossible but would love to know why.

@DavidIsaacBPS

DavidIsaacBPS commented Oct 22, 2026 •

Copy link
Copy Markdown
Author

@erickguan said:

This looks good to have though these API implementation look just like onedrive. Is there opportunity to use the same backend?

Correct. Please note Rationale in the Rationale for This Change section. Add is safer than Modify, and later diff/merge with OneDrive is easy. It can be merged now if you have a higher risk tolerance or facilities for exhaustively field testing this branch on all platforms. The current PR is very low risk as it does not affect existing services.

@erickguan

Copy link
Copy Markdown
Member
  1. Why does "Add is safer than Modify"? Can you elaborate?
  2. "It can be merged now if you have a higher risk tolerance or facilities for exhaustively field testing this branch on all platforms." I don't understand this.

@DavidIsaacBPS

DavidIsaacBPS commented Nov 13, 2026 •

Copy link
Copy Markdown
Author

Why does "Add is safer than Modify"? Can you elaborate?

I mean that adding SharePoint as a separate service introduces less technical risk than modifying the existing OneDrive service to handle SharePoint. The current implementation is an addition of a new service, and makes no modification to existing services/OneDrive. So there's no chance of breaking the existing service.

SharePoint and OneDrive are completely different services (gotta love Microsoft), particularly when it comes to file identification, etags, and security.

Combining SharePoint and OneDrive by adding sharepoint_graph_model.rs and core into OneDrive as you suggest does combine crates, but has several issues:

  • It does not eliminate any code duplication.
  • It puts two different services under OneDrive. User's have to know that some config options pertain to one but not the other, that some capabilities are different (etag, etc.), and that auth requirements are different depending on which service is actually behind the API.

"It can be merged now if you have a higher risk tolerance... I don't understand this.

I can integrate SharePoint into the OneDrive service, but I wouldn't recommend it. Every OneDrive source code file will change and some of those may be breaking/non-backward-compatible changes.

Alternatively, I could combine them as variants within the same (OneDrive) service as you suggest, but again I wouldn't recommend it for the reasons above.

OpenDAL's layout suggests that services with different semantics get their own crate and scheme even when the backends are related. If code duplication is the primary concern, one possibility would be to keep SharePoint as its own service and move the shared Graph pieces (the signer, the OAuth response model and the upload, copy and move helpers) into something like graph-common.

Please let me know how you'd like to proceed. Thx!

DavidIsaacBPS and others added 2 commits November 16, 2026 06:51
# Conflicts:
#	README.md
#	dev/src/generate/java.rs
#	dev/src/generate/python.rs
Upstream replaced `mea` with `asyncband`, moved `Metadata` construction to
`MetadataBuilder`, dropped the copy options parameter and added the
`Service::Composer` associated type. Port the service to match, align the
crate versions with the workspace, and format a test that was not rustfmt-clean.

No behavior change intended: metadata carries the same fields as before,
except that a folder no longer reports a content length (a folder's size is
not a meaningful file length).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added releases-note/feat The PR implements a new feature or has a title that begins with "feat" size:XXL This PR changes 1000+ lines, ignoring generated files. labels Nov 16, 2026

This branch has not been deployed

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

Labels

releases-note/feat The PR implements a new feature or has a title that begins with "feat" size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

new feature: support Sharepoint

3 participants