chore: mark non-public declarations @internal - #1671
Open
spydon wants to merge 1 commit into
Open
Conversation
The capability matrix extractor treats every non-underscore name in lib/ as public API, without following exports. Plenty of implementation plumbing in lib/src/ therefore counted as public surface that had to be either registered in sdk-compliance.yaml or left as an unexplained gap. @internal is the marker the extractor already honours for exactly this case, and the repo already uses it on members; this extends it to the declarations themselves. Annotates 24 declarations that are public by Dart's underscore rule but are not reachable from their package's public library: HTTP plumbing (GotrueFetch, Fetch, AuthHttpClient, GotrueRequestOptions, RequestMethodType, ApiVersion), realtime transport internals (Push, Hook, Message, Serializer, RetryTimer and their typedefs), per-package Constants, and a few helpers (Counter, ToQueryParams, SupabaseAuth, the admin OAuth client response wrappers). Deliberately excluded: anything with symbols registered in sdk-compliance.yaml as capability evidence, since annotating those would hide them from the extractor and break the drift check. That ruled out StorageBucketApi, GoTrueAdminOAuthApi, GoTrueAdminCustomProvidersApi, GoTrueAdminMFAApi, realtime's Constants and ChannelFilter. Also excluded File and YAJsonIsolate, which are reachable publicly via conditional imports and exports. functions_client gains a meta dependency, which it did not previously have. Reported public surface drops from 1952 symbols to 1831.
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (19)
📝 WalkthroughWalkthroughThe PR adds ChangesInternal API visibility
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reduces the reported public API surface across the Supabase Flutter/Dart monorepo by marking implementation-only declarations in lib/src/ as @internal, so the capability-matrix extractor no longer treats them as supported public API.
Changes:
- Annotated internal-only classes/typedefs/extensions in multiple packages with
@internal(and addedpackage:meta/meta.dartimports where needed). - Added a direct
metadependency tofunctions_clientto support the new@internalusage there. - Kept analyzer legality intact (no
invalid_internal_annotation/ cross-packageinvalid_use_of_internal_memberfallout per the PR test plan).
Reviewed changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| packages/supabase/lib/src/counter.dart | Marks Counter as internal API via @internal. |
| packages/supabase/lib/src/constants.dart | Marks Constants as internal API via @internal. |
| packages/supabase/lib/src/auth_http_client.dart | Marks AuthHttpClient as internal API via @internal. |
| packages/supabase_flutter/lib/src/supabase_auth.dart | Marks SupabaseAuth implementation plumbing as @internal. |
| packages/supabase_flutter/lib/src/constants.dart | Marks Constants as internal API via @internal. |
| packages/storage_client/lib/src/types.dart | Marks ToQueryParams extension as @internal. |
| packages/storage_client/lib/src/fetch.dart | Marks Fetch as internal API via @internal. |
| packages/storage_client/lib/src/constants.dart | Marks Constants as internal API via @internal. |
| packages/realtime_client/lib/src/serializer.dart | Marks Serializer as internal API via @internal. |
| packages/realtime_client/lib/src/retry_timer.dart | Marks reconnect timer typedefs + RetryTimer as @internal. |
| packages/realtime_client/lib/src/push.dart | Marks Callback, Push, and Hook as @internal. |
| packages/realtime_client/lib/src/message.dart | Marks Message as internal API via @internal. |
| packages/gotrue/lib/src/types/fetch_options.dart | Marks GotrueRequestOptions as @internal. |
| packages/gotrue/lib/src/types/api_version.dart | Marks ApiVersion as internal API via @internal. |
| packages/gotrue/lib/src/gotrue_admin_oauth_api.dart | Marks OAuth admin response types as @internal. |
| packages/gotrue/lib/src/fetch.dart | Marks RequestMethodType and GotrueFetch as @internal. |
| packages/gotrue/lib/src/constants.dart | Marks Constants as internal API via @internal. |
| packages/functions_client/pubspec.yaml | Adds meta dependency to support @internal. |
| packages/functions_client/lib/src/constants.dart | Marks Constants as internal API via @internal. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This was referenced Aug 7, 2026
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
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
The capability matrix extractor treats every non-underscore name in
lib/as public API, without following exports:So implementation plumbing in
lib/src/counted as public surface that had to be either registered insdk-compliance.yamlor left as an unexplained gap. This marks that plumbing@internal. The repo already uses the annotation on individual members; this extends it to the declarations themselves.Annotates 24 declarations:
realtime_clientPush,Hook,Message,Serializer,RetryTimer,Callback,TimerCallback,TimerCalculationgotrueGotrueFetch,GotrueRequestOptions,RequestMethodType,ApiVersion,Constants,OAuthClientResponse,OAuthClientListResponsestorage_clientFetch,ToQueryParams,ConstantssupabaseAuthHttpClient,Counter,Constantssupabase_flutterSupabaseAuth,Constantsfunctions_clientConstantsHow the set was chosen
Not by eye. A declaration qualifies only if it is unreachable from its package's public library, resolving
exportdirectives transitively and honouringshow/hide. That makes the annotation truthful rather than a judgement call, and keeps it analyzer-legal, since@internalon something in the public API is itself a diagnostic.Candidates were then filtered against
sdk-compliance.yaml. Annotating a class hides its members from the extractor too, so anything with registered symbols would silently break the drift check. That filter removed six:storage_client/StorageBucketApicreateBucket,listBuckets, ...)gotrue/GoTrueAdminCustomProvidersApigotrue/GoTrueAdminOAuthApigotrue/GoTrueAdminMFAApirealtime_client/ConstantsdefaultConnectionCloseTimeout)realtime_client/ChannelFilterselect)Two more were excluded for being publicly reachable in ways a naive export scan misses:
storage_client/Fileis a conditional-import typedef used inStorageFileApi.uploadsignatures, so it is effectively public.yet_another_json_isolate/YAJsonIsolatelives in_isolates_web.dartbut is conditionally exported (if (dart.library.js_interop)), so it is the package's public entry point.Effect
111 symbols stop being counted as public API. No symbol newly appears, and no registered symbol disappears.
This shrinks the backfill problem noted in #1670 by about a ninth. The remaining 930 are genuine public API that is simply unregistered; that is a separate task.
Test plan
dart analyze packages/: No issues found. This is the real gate: the analyzer reportsinvalid_internal_annotationfor anything annotated inside a public API, andinvalid_use_of_internal_memberfor cross-package use. Neither fires.Constants, which each package declares for itself; verifiedsupabase_flutter/src/supabase.dartimports its ownsrc/constants.dart, so that use is same-package.check-driftagainst a freshly extracted surface:✅ No capability matrix drift detected.dart format packages/: 0 changed.gotruetests:+448 -23, identical to unmodifiedmain(+448 -23). The 23 failures are integration tests needing a local GoTrue onlocalhost:9999and are unrelated to this change, which is annotation-only and cannot affect runtime behaviour.Note
functions_clientgains ameta: ^1.16.0dependency, which it did not previously have. Every other touched package already depended on it.Summary by CodeRabbit