Creating xoauth2 only version of the gem

[ssunday]

This gem's XOAUTH2 implementation seems to work fine with Microsoft/Outlook. My ask is to be able to make a streamlined version of this gem that only provides xoauth2 functionality—which could hopefully be then easily merged into Net::IMAP at some-point (ruby/net-imap#12). This is so it can be used with other providers without having the google specific code.

I'd be able to do the leg work in creating the xoauth2-only version, but I'm unclear on how I ought to go about it with the license as is and such.

[nfo]

Hi @ssunday . I changed the license from Apache to Unlicense. I made this choice based on https://opensource.stackexchange.com/a/4548 and https://choosealicense.com/licenses/unlicense/.
I hope it fit your needs !

I suppose you'd better create a new gem, to prevent breaking the existing stuff that is still useful to some users. So, feel free to create another gem and reuse all the code you need.

If one day, you end up being merged into Net::IMAP, let me know !

[ssunday]

@nfo Thank you so much for doing that! Yes, I think a new gem will be in order for this. I'll let you know when/if it is merged in Net::IMAP. 🙌🏻

[ssunday]

@nfo ruby/net-imap#63 Boom!

[nfo]

@ssunday Congrats ! 🎉

[nfo]

@ssunday Let me know when it's released, I'll update the README.

[ssunday]

Released as of 0.3.1 https://github.com/ruby/net-imap/commits/master

[nfo]

How do the net-imap gem differ from Ruby Standard Library ?
Are the Ruby devs expected to add the net-imap gem, so it overwrites Net::IMAP from the Standard Library ?
Is/Will the code from the net-imap gem be included in the Standard Library ? What's the process/schedule for that ?

[ssunday]

That is beyond my knowledge. It looks like https://ruby-doc.org/stdlib-3.1.2/libdoc/net-imap/rdoc/Net/IMAP.html uses an older version of the gem (?). Rails pulls in the gem https://rubygems.org/gems/actionmailer , but with no specific version so I just upgraded it on the relevant project.

[nevans]

@nfo Like @ssunday said, current versions of rails include net-imap as a dependency: https://rubygems.org/gems/actionmailer.

I actually used a forked version of net/imap as early as ruby 2.0 or maybe 1.9.3. The trick was simply putting it in the $LOAD_PATH before the stdlib net/imap. Nothing in stdlib requires it by relative or absolute path (or... at all, really!), so there really wasn't anything more to it than that. That's basically all that happens when you install the gem version.

Basically, as part of the big "stdlib gemification" project, net-imap was converted to a "default gem" in ruby 3.0 and a "bundled gem" in ruby 3.1. See https://stdgems.org/net-imap/ for the details on the stdlib => default gem => bundled gem transition. That website is a marvelous reference, in general! And its main page gives basic definitions of the different standard lib gem categories.

If you have any issues with any stdlib gems, the first place to check is by updating to the latest bundler and rubygems-update. There have been various issues with stdlib => gem that were fixed in later versions of rubygems.

---

In more detail... (please ignore me if you already knew this... and I probably got some detail wrong anyway!)

One way of thinking about it is that a standard ruby installation comes with a copy of every default gem in the ruby installation directory, e.g: /var/lib/ruby/2.7.0, and they will have gemspecs and stub directories in the Gem.path, e.g: /var/lib/gems/2.7.0. The bundled gems will be installed entirely on Gem.path, just like any other gem. Probably not in the same directory that gems you install will go, but in a later Gem.path entry.

The default ruby $LOAD_PATH, without any gems activated, will look something like:

irb(main):001:0> puts $LOAD_PATH
/usr/local/lib/site_ruby/3.0.0
/usr/local/lib/x86_64-linux-gnu/site_ruby
/usr/local/lib/site_ruby
/usr/lib/ruby/vendor_ruby/3.0.0
/usr/lib/x86_64-linux-gnu/ruby/vendor_ruby/3.0.0
/usr/lib/ruby/vendor_ruby
/usr/lib/ruby/3.0.0
/usr/lib/x86_64-linux-gnu/ruby/3.0.0

And the default Gem path will look something like this:

irb(main):004:0> puts Gem.path
/home/nick/.gem/ruby/3.0.0
/var/lib/gems/3.0.0
/usr/local/lib/ruby/gems/3.0.0
/usr/lib/ruby/gems/3.0.0
/usr/lib/x86_64-linux-gnu/ruby/gems/3.0.0
/usr/share/rubygems-integration/3.0.0
/usr/share/rubygems-integration/all
/usr/lib/x86_64-linux-gnu/rubygems-integration/3.0.0

So long as you don't disable rubygems, when require "activates" a gem, it effectively just adds all of the latest version of that gem's lib directories to the front of $LOAD_PATH. And bundler just activates a bunch of gems at once and then disables the automatic rubygems require behavior.

The real trouble comes with the gemified versions of libs like strscan or psych or did_you_mean; gems that--for one reason or another--are loaded very early, before bundler takes over. Those gems will easily activate one version of them gem automatically, and then bundler will crash because you have another version locked in your lockfile. Other stdlib gems (with C extensions) have had issues installing or running on their minimum required ruby versions. But that shouldn't be an issue with net-imap.

Even though net-imap wasn't officially converted into a gem until 3.0, it should currently be possible to simply gem install net-imap or bundle add net-imap for ruby 2.6 and up. These days, a lot of stdlib can be upgraded without upgrading ruby. There had been some issues with net-imap's dependency on digest, but those were all worked out: both by fixing compilation on older ruby versions in the latest digest release, and by removing digest as a runtime dependency of net-imap.

[nevans]

And thanks to both of you for contributing this to net-imap! Hopefully, I'll time to prepare my PRs for SCRAM-* and OAUTHBEARER early next week.