Lemmy 0.19 Breaking Changes

Dessalines@lemmy.ml to Lemmy@lemmy.ml – 414 points –

We are getting closer to the next major release. This version will have many breaking changes, so we are listing them here for app and client developers to adjust their projects.

As we prepare for the release of Lemmy 0.19.0, we'd like to provide any app or client developers ample time to upgrade their apps, as well as discover any problems, before we do the release. This will be at least 4 weeks from now (but likely longer).

Server admins can also upgrade to the latest release candidates for testing. Be aware that they are still unstable and shouldn't be used in production. As with any upgrade it is important to have working backups in place.

It should be possible for clients to support both Lemmy 0.18 and 0.19 without major workarounds. If backwards compatibility is causing you trouble, comment below and we will help to find a solution.

To test, you can point your app to the following test instance running a release candidate of 0.19.0: https://voyager.lemmy.ml

A diff of API changes is here: lemmy-js-client API changes from 0.18.3 -> 0.19.0-rc's

Note for developers not using typescript or rust:

If you'd like to auto-generate an API client for your language, you can try out @MV-GH's lemmy_openapi_spec, or (if in kotlin), use Jerboa's script here.

Major Changes

Authentication

Previous Lemmy versions used to take authentication as query/post parameters. This is insecure and unnecessarily complicated. With 0.19, the jwt token can be passed either as cookie with name auth, or as header in the form Authorization: Bearer .

A major advantage is that this allows us to send proper cache-control headers, with responses to unauthenticated users being cacheable. It also prevents token leaks in web server logs. The login and registration endpoints attempt to set the cookie automatically. If that is supported on your platform, you don't have to worry about the authentication token at all.

In order for your client to be compatible with both Lemmy 0.18 and 0.19, you should send auth in both ways. Meaning with each API call, send the old auth query/post parameter, as well as the new header or cookie.

A few PRs detailing these changes:

Users can block instances

Users can now block instances, so that their communities are hidden from listings. This is done via POST /api/v3/site/block with parameters int instance_id, bool block.

https://github.com/LemmyNet/lemmy/pull/3869

New sort options

A new scaled sort option has been added. This sort is identical to the Hot sort, but also takes into account the number of each community's active monthly users, and so helps to boost posts from less active communities to the top.

https://github.com/LemmyNet/lemmy/pull/3907

2FA / TOTP Rework

Two-Factor-Authentication is now enabled in a two-step process to avoid locking yourself out. Now a secret needs to be generated first with POST /api/v3/user/totp/generate (no parameters). The generated token needs to be added by the user to an authenticator app.

Once this is completed, 2FA can be enabled with POST /api/v3/user/totp/update. This takes a string parameter totp_token (generated by authenticator app), and boolean enabled. 2FA can be disabled again with the same update endpoint. Additionally, the 2FA algorithm has been changed to SHA1 for better compatibility.

The update disables 2FA for all accounts, so that users who are locked out can use their accounts again, and to ease the transition to the SHA1 algorithm.

https://github.com/LemmyNet/lemmy/pull/3959

Timestamps now include timezone

Previous Lemmy versions used timestamps without any timezone internally. This caused problems when federating with other software that uses timezones.

Going forward, all timestamps in the API are switching from timestamps without time zone (2023-09-27T12:29:59.113132) to ISO8601 timestamps (e.g. 2023-10-29T15:10:51.557399+01:00 or Z suffix). In order to be compatible with both 0.18 and 0.19, parse the timestamp as ISO8601 and add a Z suffix if it fails (for older versions).

https://github.com/LemmyNet/lemmy/pull/3496

Cursor based pagination

0.19 adds support for cursor based pagination on the /api/v3/post/list endpoint. This is more efficient for the database. Instead of a query parameter ?page=3, listing responses now include a field "next_page": "Pa46c" which needs to be passed as ?page_cursor=Pa46c. The existing pagination method is still supported for backwards compatibility, but will be removed in the next version.

https://github.com/LemmyNet/lemmy/pull/3872

New endpoints for export/import of user settings data

Users can now export their profile settings data (including subscriptions and blocklists) via GET /api/v3/user/export. The returned JSON data should not be parsed by clients, but directly downloaded as a file. Backups can be imported via POST /api/v3/user/import.

https://github.com/LemmyNet/lemmy/pull/3976

Make remove content optional during account deletion

When a user deletes their own account using POST /api/v3/user/delete_account, there is a new parameter called delete_content. If it is true, all posts, comments and other content created by the user are deleted (this is the previous default behaviour). If it is false, only the user profile will be marked as deleted.

https://github.com/LemmyNet/lemmy/pull/3817

Outgoing Federation Queue

The federation queue has been rewritten to be much more performant and reliable. This is irrelevant for client developers, but admins should look out for potential federation problems. If you run multiple Lemmy backends for horizontal scaling, be sure to read the updated documentation and set the new configuration parameters. The Troubleshooting section has information about how to find out the state of the federation queues.

https://github.com/LemmyNet/lemmy/pull/3605

61

scaled ranking is gonna be a gamechanger, I don't subscribe to a few communities just because they will blow out my other ones

Honestly, scaled ranking and user-level server bans are huge deals. This is really exciting.

Also, importing/exporting user data will make it easier to transfer your account to a different instance. I'm mostly excited for scaled ranking though.

I agree - I don't even sub to all that many communities, and just had to move instances this week - it was a clunky process to say the least.

Yeah, I can't wait to see how this works in practice. Wonder if they'll find something similar with active posts, and hopefully a way to not see the same post over and over.

I created a workaround for that at https://schedule.lemmings.world - you can select which communities you want to be notified about new posts daily/weekly/monthly etc. You can also create multiple such schedules for a single community, meaning you can easily get notified every hour if that's what you wish.

Off topic here but from the looks of it Lemmy requires a serious amount of time and work. Is the development team working on this full time in lieu of a full time programming job? Or is a passion project in addition to your real live duties?

@nutomic@lemmy.ml and I work full-time on lemmy, and there's a large number of additional contributors, helping out not just with code, but with translations, documentation, moderation, etc. As donations increase, we'd like to add more full-time/paid devs to our little co-op (we're in the process onboarding two more rn).

Full time, off of donations and also they are sponsored by some open-source group iirc

Absolutely stellar work from every person who contributes to Lemmy. With each new release Lemmy is becoming more and more accessible and just plain better.

Thank you all for your hard work in making Lemmy even better. I'm really happy to see the ability for users to block instances themselves, seems like it was a widely requested feature.

We can finally stop seeing de-federation post crying about other political views.

I think the main advantage will be that it's much easier to choose a home instance, because you don't have to select one that defederates according to your own preferences. It'll make Lemmy more accessible for new users.

And further thanks for taking this much care wrt backwards compatibility and helping clients avoid breaking.

Thanks! Ya that one should be very useful, and now apps won't have to hack it on afterwards.

helps to boost posts from less active communities to the top

Nice!! This and the instance-blocking are welcome changes.

Users can block instances

Finally!

I've had enough creepy/disgusting furry and pedophile drawings on my feed. That "yiffit" instance will be the first that I block.

So long hexbear

Doesn't sound like it'll block the users so the battle is only half won.

I use the app Connect for Android which has an insurance blocking feature already. I don't see posts or communities from their users, and when they comment on a post I can see, the content of their comment is collapsed by default. I can still see it if I click. It's a good system, I think.

Yeah it would be nice for a web version of connect to use on desktop. Can't type to save my life on mobile, fingies too strong.

Just a note: Datetime without timezone is a valid ISO8601 datetime, so no library should fail when trying to parse the old dates.

Yeah, I took out the +Z concatenation in my frontend ahead of 0.19.0 support, and everything works fine without it.

Well, probably not fine - if it follows the standards, it should assume the local timezone, so unless your server is in the UTC timezone, you may be showing wrong dates.

Well, all the places that used that were passing it to a function that fuzzed the time somewhat. e.g. 2023-09-01 13:20:55.123456 becomes "1 mo ago". So timezone really didn't provide any benefit there.

A major advantage is that this allows us to send proper cache-control headers, with responses to unauthenticated users being cacheable.

Note for people using Cloudflare that it has some pretty dumb caching behaviour so you will want to make sure to disable it for any endpoint that may be authenticated.

I don't think I wrote down the exact behaviour but IIRC it basically ignores the Vary header. So it will serve the "unauthorized" page to future requests that have credentials. I think it will at least not cache responses with authentication if vary is included but it will cache the unauthenticated ones.

Shouldn’t SHA1 not be used for anything since it is insecure? Why not SHA256?

Because hardly any popular 2fa authenticator apps have implemented sha256 yet. No point putting the chicken before the egg.

We currently use SHA-256 but too many authenticator apps ignore the alg parameter, and don't know how to support the spec which should allow different variants.

While SHA1 might be considered problematic security-wise in terms of collision (using it for certs today would be very bad, for example), it is not problematic in terms of preimage attacks (even MD5 isn't broken that way IIRC), which is what truly matters in the context of 2FA / TOTPs

As for "why not SHA256", compatibility

Looks really good!

Any chance of user set and saved groupings of communities, like multi reddits, in the future?

With the improvements listed here, combined with the latest mobile clients, some way to group similar interest communities, would make it almost feature complete, for me :)

There are some open issues, but we have too many other things to focus on, so we won't likely get to it soon.

Great job guys and other contributors πŸ˜‰πŸ‘

Thanks a lot to all contributors for the hard work!! πŸ’ͺ

As someone that got to watch some of these major changes taking place in real time, I'd just like to say well done and thanks everyone.

will this require a total rewrite of my docker-compose? Or will I be able to manage with doing some slight edits?

Probably not a total rewrite. When we do the release, I'll let you know.

Will user blocking actually work the way it should now or is it still useless garbage that enables harassment?

If there are breaking changes, why not update the MAJOR version? It's what semantic versioning is for:

Summary

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes
  • MINOR version when you add functionality in a backward compatible manner
  • PATCH version when you make backward compatible bug fixes

There's a bit more to it than captured in the summary, which is why it's just a summary of the spec and not the actual spec.

From a bit further down on that page:

  1. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Lemmy is still in major version zero, so it can make breaking changes without incrementing the major version and still be in compliance with the spec. This way, projects won't have their first "real" version be something like v123.0.0.

Lemmy still being v0.x also serves as kind of a warning to app developers that changes like this may be made at any time.

From your link:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.