Looks like we got a consensus to confine SPI in certain modules. Here are a few candidates: 1. polaris-core 2. All modules under /api 3. polaris-runtime-service, this module is a bit controversial, as it holds a lot of implementation as well as interfaces. Options would be 1. to move interfaces to the polaris-core, 2. to create a new module to hold these interfaces.
Yufei On Mon, Aug 18, 2025 at 3:33 PM Michael Collado <collado.m...@gmail.com> wrote: > > If a downstream project uses CDI and something comes out of alignment, > that is usually detected at compile time, so it's still as explicit as > renaming a method IMHO :) > > It is certainly obvious to the owners of the downstream project, but in the > context of this discussion, it's not visible to PR authors who may not be > aware of the downstream compilation effects. > > I'm fully in favor of an API module that is intended to be consumed by > outside projects. I kinda thought that's what polaris-core was intended to > be. That's where pretty much all of the central Polaris API interfaces and > implementations are defined. These were originally scoped to be accessible > from even outside of the context of a web service application. > Additionally, polaris-service-common defines many interface definitions > that are configurable via the application.properties file. I know there is > a lot more defined in that module aside from just the interface > definitions, so maybe there are steps to take to isolate the intended > extension points, as you suggest. > > On Fri, Aug 15, 2025 at 9:54 PM Dmitri Bourlatchkov <di...@apache.org> > wrote: > > > Hi Michael, > > > > I'm not sure I completely understand your point about explicit vs. > > implicit. > > > > From my POV, existing Apache Polaris code is always explicit since it is > > available for inspection end-to-end, injection points are annotated and > > injection behaviour is controlled by explicit configuration. > > > > If a downstream project uses CDI and something comes out of alignment, > > that is usually detected at compile time, so it's still as explicit as > > renaming > > a method IMHO :) > > > > For downstream projects, even non-CDI usage is always implicit because > > anything that is callable can be called somewhere and it is impossible to > > predict what is used. As Polaris code itself shows, even private fields > and > > methods from upstream projects may be used. > > > > I fully support establishing a well-defined SPI surface. However, I do > not > > think > > it is quite possible to achieve that without first going through a phase > of > > risky / breaking changes (because of the above). Ideally I think Polaris > > should > > define SPI not only by means of java visibility modifiers or annotations, > > but by > > defining an isolated module (jar) in the codebase. > > > > I suppose the transition to such an SPI module is going to be turbulent > for > > downstream projects, but the end result should allow better control over > > SPI evolution. > > > > WDYT? > > > > Thanks, > > Dmitri. > > > > On Fri, Aug 15, 2025 at 10: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/ > > > > > > > > > > > > > > >
