Proposal: Streamlining ATProtoKit Session Configuration for Better Usability and Flexibility

[MasterJ93]

As it stands, there does seem that there’s some difficulty with using ATProtocolConfiguration. At the same time, based on what I’m reading in terms of what people want to see, this class is going to end up getting very, very bloated, trying to do too much for too many use cases, and as a result, it will fail in all of them. I don’t like this and we need to separate things. As a result, this is what I want to do (part of this was in the works, but the following is more fleshed out).

• ATProtocolConfiguration will be only for app password-related management. This is because 1) it’s the most widely used way of logging into atproto services, and 2) OAuth in atproto is still in the early phase. Overtime, this might change, but for right now, this is how things are.

• SessionConfiguration will be the generic protocol that will ATProtoKit will accept for session management. This will have the basic things that the class will use in order to handle authentication requests. While OAuth is still being implemented, there are some who are using packages that include atproto OAuth. For that use case, I highly recommend using this protocol for the most flexibility and integrate that library with this protocol.

• The implementations for createAccount, getSession, refreshSession, resumeSession, and deleteSession will be moved over to SessionConfiguration as default implementations. ATProtocolConfiguration will use the default implementations as-is. This means that, if you don’t agree with the way it’s implemented, you can always override this with your own class, pass your class to ATProtoKit, and experience the same results.

• The helper methods will move over to the ATProtoTools class.

• One of the things that I’ve seen people have difficulty with is the UserSession struct. This was supposed to be a portable way to move properties related to the user account and it was supposed to be straightforward. Unfortunately, it seems this has caused more trouble than what it’s worth and I apologize for that. But I don’t want to lose these properties either since these can potentially be very important for developers if they need it. Therefore, I’ve opted to move them into SessionConfiguration. Now, you have direct access to them without the need to use the session method.

• There will be a new initializer. This initializer will let you pass an access token and refresh token, as well as, optionally, the URL of the Personal Data Server (PDS). The access token is optional as well if you feel you want to always have the session refreshed for every app launch. This will fix the issue where you want to pass in the tokens for each app launch.

• For security reasons, ATProtocolConfiguration will set the appPassword field to private. While the initializer will still take the password, it will only use it once. authenticate will remove it from the field when it has completed the authentication. If this is too much, however, then I could probably make it public, but it is your responsibility to set it to nil.

• ATOAuthConfiguration will still be developed, especially for those who just want something straightforward without the need for an additional dependency. But this will still take some time. I hope to have an experimental version as a separate branch in the coming weeks.

This should be it. With that said, some people may actually set like it the way it is now. For that use case, I will create another class that works a similar way to how it works now. However, it will be considered deprecated and I would encourage you to try out this new way instead.

This is something I need substantial feedback and I implore you to let me know what you think of this. Please let your voice be heard so I know what pain points that haven’t been addressed with this proposal and what seems to work for you. Thank you for taking your time in reading this.

[EricWVGG]

Is ATProtoKit able to reach unauthenticated endpoints?

ex. go to bsky.app in an "incognito" window — you can view profiles, do basic searches, look at threads, etc.

I am working on a Bluesky app that (yes, weirdly) doesn't need sessions at all. I'd like to flip to your lib, but I don't want to require users to log in, that would add a lot of unnecessary friction.

[MasterJ93]

Yes you can. You can explicitly remove the sessionConfiguration argument from the main ATProtoKit class and use them without issue.

Please keep in mind, however, that there are limits to this: not due to ATProtoKit itself, but due to the API calls within Bluesky and the AT Protocol. If you get an error that authentication is required, then it's likely that the API call doesn't let you use that API without authentication first. There are also a few API calls where the output will be different depending on if the user is authenticated or not. I do understand, however, that I haven't communicated this well in the documentation, so I'm looking for ways to better state this.

Perhaps I could add a note to the documentation of each method that lets you call it without the need of authentication, followed by an article that lists all non-authentication and authentication-optional methods. I will consider this in a future update.

[EricWVGG]

A separate list would be overkill imo… if your documentation ultimately has a list of all endpoints, that could simply have a column (if tabular) or an asterisk or some mark to indicate whether it's an open endpoint.

Thank you for the prompt response, I'll give that a try later this coming week.

[MasterJ93]

If having a list of all of the non-authentication and authentication optional methods in an article is considered overkill, then perhaps I might be overthinking things. But I will indeed make sure to have a note in each method call that lets you use the method with no authentication, or that gives you the option to use it without authentication (while noting the limitations of what will not be displayed if it's used without authentication).