Thanks Dennis for listing these SPIs. To make it easy for developer to understand, I think we have multiple options
1. Annotation-based approach, Apache Spark adopts it, e.g., @Stable, @@Experimental. It is fine-grained, but it brings a lot of maintenance costs. For example, which interfaces should be annotated as stable, when can we move an experimental interface to a stable one. 2. Convention-based approach, Apache Iceberg adopts it, e.g., we just say that interfaces, public classes/methods in certain modules are considered as SPIs. For example, Polaris core is a good candidate. Personally, I'd love to use the Iceberg mode as it is much simple. There are always exceptions like we said certain interfaces are considered as SPI even if they are not in Polaris core, which we can bring up case by case. Yufei On Fri, Aug 15, 2025 at 7:42 AM Michael Collado <collado.m...@gmail.com> wrote: > Possibly a point with mentioning, then, is that dependencies must be > explicit in order to be clear about where there’s an extension contract. > Some of the CDI work has led to things being less clear as things that were > explicitly passed around are now simply @Injected whenever they’re needed. > That makes for tidier method signatures, but also makes it impossible to > identify things that are expected to be available for dependents. > Particularly around these SPI types, we should take care when moving things > from being explicit to implicit. > > Mike > > On Thu, Aug 14, 2025 at 9:08 PM Dennis Huo <huoi...@gmail.com> wrote: > > > Thanks for starting this discussion! Definitely a current gap not having > > well-established SPI delineations. > > > > As a starting point, certainly any of the runtime-configurable > > factory/supplier types demonstrate intent for service-provider > > extensibility achievable without modifying any Polaris code directly, > (i.e. > > fork-free customizations). Such factories/supplies, the types they > > construct, and the method signatures of those types constitute the > baseline > > core SPI for Polaris. > > > > A cursory search via "@Identifer" yields at least the following > > (non-exhaustive) list of starting points: > > > > ActiveRolesProvider > > CallContextResolver > > FederatedPrincipalProvider > > FederatedRoleProvider > > FileIOFactory > > IcebergRestOAuth2ApiService > > MetaStoreManagerFactory > > OidcTenantResolver > > PrincipalMapper > > PrincipalRolesMapper > > RateLimiter > > RealmContextResolver > > TokenBrokerFactory > > TokenBucketFactory > > UserSecretsManagerFactory > > > > Probably the ones that are most complex in terms of type-dependencies in > > method signatures are: > > > > CallContextResolver > > MetaStoreManagerFactory > > RealmContextResolver > > > > Corresponding to these constructed types: > > > > PolarisMetaStoreManager > > BasePersistence > > IntegrationPersistence > > TransactionalPersistence > > CallContext > > PolarisCallContext > > RealmContext > > > > This also implies that method arguments provided into instances of those > > types would need to be at least backwards-compatible. > > > > In general, this doesn't mean those interfaces necessarily can't be > > evolved, but at least interface evolution of such SPI classes should be > > discussed and voted on. > > > > On Tue, Aug 12, 2025 at 3:09 AM Robert Stupp <sn...@snazy.de> wrote: > > > > > Hi all, > > > > > > Recently it became apparent that the community has no single opinion > > > about what an integration point that downstream consumers can rely on > > > in terms of availability, stability and most importantly functional > > > and behavioral contracts is. > > > > > > The Polaris code base itself is still pretty fresh/young, started > > > about one year ago. It is quite natural that things are not yet > > > optimal and evolution and changes happen to meet everybody’s > > > expectations and the project’s needs now and in/for the future. > > > > > > Polaris is an open source project to be used by many users. Many run > > > it “as is” (aka as distributed by the Apache Polaris project) and some > > > use it as a foundation to customize it with their own functionalities. > > > > > > The overarching goal of the project is (I think) providing a stable > > > system (runtime) without neglecting the necessities (like security) > > > while improving the observed behavior (like performance) and being > > > open for new features & functionalities and consistently+constantly > > > removing tech-debt. > > > > > > Two recent PRs simplifying some code complexities in Apache Polaris > > > and fixing runtime penalties for all Polaris users received reviews > > > mentioning a “...service provider with a custom persistence backend…” > > > [1] and "...production deployment … with custom implementations..." > > > [2]. > > > > > > As the Apache Polaris project has no clear definition of which parts > > > of the code base are extension points (think: SPIs), it is impossible > > > for contributors to Apache Polaris to know what a “breaking change” > > > for “custom implementations” is. > > > > > > I would like to start this discussion and look forward to the > > > community’s opinion, both from users that use Polaris “as is” and > > > those who “extend Polaris”. > > > > > > Robert > > > > > > PS: The contributing guidelines [3] do not define what public > interfaces > > > are. > > > > > > [1] > > > > https://github.com/apache/polaris/pull/2262#pullrequestreview-3099480896 > > > [2] > > > > https://github.com/apache/polaris/pull/2277#pullrequestreview-3099564976 > > > [3] https://polaris.apache.org/community/contributing-guidelines/ > > > > > >
