Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OWIN versioning #25

Open
serialseb opened this issue Oct 5, 2014 · 4 comments
Open

OWIN versioning #25

serialseb opened this issue Oct 5, 2014 · 4 comments

Comments

@serialseb
Copy link
Contributor

As it stands, the versioning section in the OWIN specification does not allow evolving specifications easily.

According to versioning rules, a server may advertise which version of owin it supports. This is done so as to not break ABIs for components down the pipeline. Any change to such ABIs (aka AppFunc and any key in the environment dictionary that is declared in a specification) requires a major version change. Additions of optional keys should only change the minor version.

With the proposal of ClaimsPrincipal used for a security key, we add another ABI to that list, as well as a dependency on a specific version of the framework.

Such a component is deemed to require owin 1.1 (the specification) where in fact it can happily run on any server advertising owin 1.0 as long as the execution pipeline runs in .net 4.5.

It seems unlikely that any component requiring keys in owin 1.1 would not run on an owin 1.0 server. It seems even more unlikely that we would get any benefits by enforcing minimum versions on the server.

What is the meaning of "owin.Version" in this case? In this state, the server+application combo is a mix and match of compatible components that have little to do with having an "owin.Version" at all, and introducing versioning as change control doesn't seem to trigger any benefits and looks to me as a solution trying to find a problem.

Futhermore, the following is underspecified and currently inachievable:

  • All implementers SHOULD clearly document the full version number(s) of the OWIN standard they support.

How? What's an implementer? What version do you support? "Supports OWIN 1.1 on any OWIN 1.0 host" seems like a very poor way of communicating your compatibility.

Proposal:
#1. Can 1.1 and work on 1.0.1

As such, I propose to can 1.1 altogether, and work on defining 1.0.1 (or second edition) that replaces 1.0, and moves all optional keys away from the core specification. Each key or set of key scheduled for 1.1 (request id and principal) would be moved to its own specification in the CommonKeys addendum, as that list is forward referenced from the main spec already. There would be no change to surface area or compatibility as it stands, as such conforming 1.0.1 to it's current versioning scheme.
#2. Change the CommonKeys "addendum" to a registry

This would also not change any of the current validation rules but would allow defining rules on how to add keys to that specification.
#3. Version key specifications independently from owin

As I do not suggest to move any of the keys part of 1.0 in that registry, this would also have no effect for those keys.

For the keys in CommonKeys, the problem is more complex. Additions to the list or changes to existing keys that are backward compatible have no impact on OWIN versioning, but if it happened the current specification would force OWIN itself to change due to any change to those keys that are "STRICTLY OPTIONAL". I suggest as part of Owin 1.0.1 we drop the requirement (and the specifier strictly).
#4. Differentiate standard common keys and vendor keys

Keys in the common set published under the owin name should go through the same criteria as our main specification.
Vendors should be encouraged to poublish their own keys, in a separate section that is reference-only and clearly marked as non-standard.
#5. Define a minimum criteria for owin specifications to be adopted, and vendor registrations to be added

Assuming that specifications ought to be adopted by rough consensus, it would be important to add a few guidelines as to what may or may not be edited out on the registry.

Such things as:

  • for owin standards, interoperability between vendors
  • for vendor extensions, a specification, contact details and additional metadata.

That's all for now.

@panesofglass
Copy link
Member

👍 I need to re-read this more closely, but I'm generally a fan. Thanks! I've already added a 1.0.1 milestone.

@panesofglass panesofglass modified the milestones: 1.1 Specify Middleware, 1.0.1 Optional Keys Sep 1, 2015
@panesofglass
Copy link
Member

I really like this and would be up for calling a vote. Others? @khellang @damianh @Tratcher @skoon

@khellang
Copy link
Member

👍

@Tratcher
Copy link
Contributor

This sounds productive overall.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants