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/ > > > > > >
