[🚧 WIP] SASL refactoring and new mechanisms

[nevans]

NOTE: This PR started as a big rough-draft for many of the other PRs listed below. Rather than close the PR and create a new tracking issue, I've been keeping the branch around as a set of experimental implementations for some of the TODO list items, while cherry-picking parts of it into their own PRs when they are ready.

• Issues and PRs
  • Closed
  • Open
• 🔒✨ Adds new mechanisms:
  • EXTERNAL
    • [x] #79
    • [x] #170
  • ANONYMOUS
    • [x] #81
    • [x] #169
  • OAUTHBEARER
    • [x] #80
    • [x] #171
  • SCRAM-SHA-1, SCRAM-SHA-256
    • [x] #54
    • [x] #64
    • [x] #172
• 🔒 Better support for the core RFCs (3051, 4422, 4959, and 9051)
  • [x] #34
    • [x] #90
    • [x] #180
  • [x] #179
    • Needed for SCRAM-* and to support net-smtp, which already followed the RFC on this.
  • [x] #184
  • [ ] Cancel SASL authentication after client-side exceptions
• API improvements
  • [x] #62
  • [x] #167
  • [x] #168
  • [x] #177
  • [x] #187
  • [x] #195
  • [x] Results should encapsulate the authenticator object, which may contain server-sent data.
    • Although there is room for improvement, this was mostly done by:
      • [x] #179
      • [x] #184
    • ~AuthenticationSuccess (subclass of TaggedResponse)~
    • AuthenticationFailed ~(subclass of NoResponseError)~
    • AuthenticationIncomplete (includes response attr)
    • AuthenticationError
    • AuthenticationCanceled ~(subclass of BadResponseError)~
  • [ ] #82 This PR originally had an implementation of this, but it was over-complicated and removed to simplify the API for the v0.4.0 release.
  • [ ] Consider supporting simplifications of the process state machine, e.g:
    • Maybe support specific conversation shapes with a single callback method per interaction. I think this is what mongo does.
    • Or, use blocks and yields to invert the API like Enumerable#each vs Enumerator#next. This is closer to the net-smtp API and could greatly simplify the mechanism implementation. It is a little bit trickier to adapt this style to multiple threads and Net::IMAP's receiver loop.
• Share the net-imap SASL implementation with other gems #23.
  • [x] Add a protocol adapter layer that answers all of the questions from https://www.rfc-editor.org/rfc/rfc4422.html#section-4 and can be used to simplify inclusion in other gems, e.g. net-smtp, net-pop, net-ldap, mongo, etc.
    • [x] #183
    • [ ] #194
  • [x] Create PR for net-smtp: https://github.com/ruby/net-smtp/compare/master...nevans:net-smtp:net-imap-sasl.
  • [ ] Create PR for net-pop
  • [ ] Create PRs for net-ldap, mongo, and possibly others...
• Improved documentation
  • [x] #166
  • [x] #176
• Code re-organization
  • [x] #22
  • [x] #165

[nevans]

n.b this PR is currently based on #70, #71, #72, #73, #74, #75, and #76. I can rebase part of all of this on master, but I think those will be merged before this is.

Also, it's currently failing 2.6, because I used some numbered parameters in a few places. As discussed on #68, we can remove support for 2.6.

[Neustradamus]

@nevans: Good job!

[Neustradamus]

@nevans: Happy New Year!

Little question, have you a timeline?

[Neustradamus]

@nevans: I think that you can remove CRAM-MD5, DIGEST-MD5, LOGIN from all.

[Neustradamus]

@nevans: Thanks to work on this important part!

I hope that this part can be official soon ^^