Proof of concept: MastodonMinServerVersion annotation

[PattaFeuFeu]

Description

Our Wiki mentions:

All methods are annotated using a @MastodonMinServerVersion runtime annotation. The goal of this annotation is to specify the minimum server version that is required in order to make this call successful. During library initialization, we fetch the server version from the instance. When the method is invoked, we compare versions and if requirements are not met, we will throw a BigBoneVersionException. The caller can then decide how to proceed further (e.g. call another method or fail).

So far, that was not at all the case. But I like the idea, so I wanted to implement a proof of concept which is how this PR should be seen: Not a mergeable change set, but grounds for discussion.

I have added the annotation and additional functions to check if a called method’s min version is higher than or equal to the known instance version.

I’m currently not too happy with the InstanceMethods::getInstance.requireMinVersion(client) call and that would be my main criticism for the current solution. My knowledge regarding annotations, reflection, or annotation-based code is very much in its infancy so I’m sure there are better solutions that I’d still need to learn about. ksp might be an option to auto-create the boilerplate code so that we only need to add the annotation and then ksp handles the rest for us and automatically adds code similar to what I’ve added for getInstance as an example for now.

Before I continue with this, I’d like to find out what you think of this. Is this a good way forward? Would you like a different approach?

Type of Change

(Keep the one that applies, remove the rest)

• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Dependency addition

Breaking change

Methods annotated with @MastodonMinServerVersion may now throw a BigBoneVersionException which leads to errors from Java callers if they’re not explicitly handling that exception (or its parent Exception).

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Mandatory Checklist

• My change follows the projects coding style
• I ran gradle check and there were no errors reported
• I have performed a self-review of my code
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• KDoc added to all public methods

[PattaFeuFeu]

This might need to be a bit more lenient, seeing as Mastodon doesn’t follow semantic versioning to the letter at least when it comes to release candidates, as can be seen in this example JSON:

bigbone/bigbone/src/test/assets/instance_extended.json

Line 4 in b42c060

"version": "4.0.0rc1",

They only switched to a more SemVer-friendly variant starting with 4.2.0-beta3 in mastodon/mastodon#26653:

https://github.com/mastodon/mastodon/blob/v4.2.0-beta3/lib/mastodon/version.rb#L36-L38

[bocops]

I agree with your self-criticism. Annotations are great if they help remove boilerplate code, or at least having to write it ourselves - but having to add a call to requireMinVersion() in every API method is the opposite. As long as that is necessary, we might as well just add a minMastodonVersion String as another parameter to our client.getMastodonRequest(), and then do the version check in that function. That aside, if there is a way to properly achieve this using annotations, the rest of it looks good.

The only thing I'd like to see for the moment is an option to disable version checks when building the MastodonClient (or reduce them to less than an exception), so that library users at least have the choice to use BigBone with all those platforms that offer a Mastodon-compatible API while using very different versioning, for example Pixelfed, GotoSocial, Hometown, and probably many more.

Long-term, I believe having a proper way to support different platforms would be useful (see #226).