search

frasertweedale / hs-jose

Haskell JOSE and JWT library
http://hackage.haskell.org/package/jose
Apache License 2.0
122 stars 46 forks source link

improve header protection ergonomics (breaking change) #128

Closed frasertweedale closed 2 months ago

frasertweedale commented 6 months ago

Changed the header protection data types for better ergonomics (#125). Previously, () was used for serialisations that only support protected headers (thus, a single constructor). This release introduces the new single-constructor data type ProtectedOnly to replace the use of () for this purpose. This is a breaking change and some library users will need to update their code.

The Protection type has been renamed to ProtectionOptional, with the old name retained as a (deprecated) type synonym.

The ProtectionIndicator class has been renamed to ProtectionOptionality, with the old name retained as a (deprecated) type synonym.

Added some convenience header and header parameter constructors: newJWSHeaderProtected, newHeaderParamProtected and newHeaderParamUnprotected.

Fixes: https://github.com/frasertweedale/hs-jose/issues/125

frasertweedale commented 6 months ago

ping @ericpashman ^ could you please review and provide feedback?

ericpashman commented 6 months ago

Hi, Fraser. I haven't used this yet, but reading the code and Haddocks, I do think these changes make the purpose and usage of the header-protection functionality much clearer.

At risk of bike-shedding, and with the caveat that I'd probably have a different preferred naming scheme every time I look at this, here are the names that make the most sense to me right now.

Class: ProtectionIndicator -> ProtectionOptionality -> ProtectionSupport
Type: Protection -> ProtectionOptional -> OptionalProtection
Type: () -> ProtectedOnly -> RequiredProtection

In particular, calling the class ProtectionSupport seems closer to the language of the documentation ("serialisations that only support protected headers") than my originally suggested ProtectionOptionality.

frasertweedale commented 2 months ago

@ericpashman thanks for your feedback. There's a nice balance to your suggested names and I have adopted them. I will push the changes shortly, and merge after testing. Then a release is not far away!

Thank you for you patience and collaboration!