Evolving axum-sessions

[maxcountryman]

Hi folks,

I wanted to share some experimental work I've done recently to look at reworking this crate with tower-cookies in the hopes that you all might have some feedback and share your input.

The design of this new approach works like this:

1. We create a tower service that wraps tower-cookies
2. We look for a cookie by name in the request; when we find one we build a session from it and when we don't we create a new session
3. We attach the session to the request via an extension
4. We persist the session in a store and set the cookie if and only if it's been modified

This is more or less how axum-sessions works today with some ergonomic improvements in the code itself. However, that's largely where the similarities end.

With tower-sessions, I've also implemented sessions and session stores directly, and dropped the dependency on a third-party crate. This will help us ensure we can iterate on the core pieces of the crate without needing to wait on upstream updates. It also means that stores can be provided as part of the crate directly, placed behind feature flags.

Some notable evolutions:

• Sessions can be added directly to requests as extensions without the need for two extractors (internally they use a Mutex around their shared mutable state)
• We no longer use async-sessions
• We use the cookie crate via tower-cookies
• We still expose a public SessionStore trait, but will provide common stores like Redis and SQL out of the box
• This is being written as a new crate

On that last point, I've started implementing this as its own crate. It's a break from the direction of axum-sessions and is written for tower from the ground up. That said it works with axum and the intent would be to replace this crate going forward.

I will share a new repo shortly so you all can take a look. However, I would love your feedback here.

// examples/counter.rs
use std::net::SocketAddr;

use axum::{
    error_handling::HandleErrorLayer, response::IntoResponse, routing::get, BoxError, Router,
};
use http::StatusCode;
use serde::{Deserialize, Serialize};
use tower::ServiceBuilder;
use tower_sessions::{time::Duration, MemoryStore, Session, SessionManagerLayer};

#[derive(Serialize, Deserialize, Default)]
struct Counter(usize);

#[tokio::main]
async fn main() {
    let session_store = MemoryStore::default();
    let session_service = ServiceBuilder::new()
        .layer(HandleErrorLayer::new(|_: BoxError| async {
            StatusCode::BAD_REQUEST
        }))
        .layer(
            SessionManagerLayer::new(session_store)
                .with_secure(false)
                .with_max_age(Duration::seconds(10)),
        );

    let app = Router::new()
        .route("/", get(handler))
        .layer(session_service);

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    axum::Server::bind(&addr)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

async fn handler(session: Session) -> impl IntoResponse {
    let counter: Counter = session
        .get("counter")
        .expect("Could not deserialize.")
        .unwrap_or_default();

    session
        .insert("counter", counter.0 + 1)
        .expect("Could not serialize.");

    format!("Current count: {}", counter.0)
}

[maxcountryman]

I've put together a working prototype over in the tower-sessions repo.

I would very much appreciate any feedback folks have. I think tower-sessions would largely replace axum-sessions so the goal is to ensure we're both covering the use cases of this crate as well as fixing as many of its pain points as we can.

[BurntNail]

Hey dude,

Apologies - I’m not sure if it was the same way in the original, but here are two suggestion regardless.

Entry API

In HashMaps, there’s a commonly used Entry API, which could be quite useful here.

Strongly typed sessions

I see that what gets inserted into the session is strongly typed, but it looks like the session itself is 'stringly' typed. Any chance you could expose an API similar to the Query extractor where it takes a generic type. You could also take this further by using this current Session as a WeakSession, and then having a SessionStore which only stores one struct for the session, so you avoid all the string-typing and possible optionals.

[maxcountryman]

Correct me if I'm wrong, but tower-sessions only uses tower-cookies to store & retrieve the session ID, right?

That's right.

The session itself doesn't need to be (de)serializable, does it?

It would be difficult to support arbitrary storage backends without this.

This is important because we convert the session data to a JSON representation before actually storing it, which means we can support virtually any backend. (It doesn't necessarily have to be JSON, but it is important that we know it's Serialize.)

The other thing to point out is that sessions are typically key-value stores that have some metadata (like expiration) associated with them. So supporting any T would still require wrapping this type such that the session metadata and indeed the session API itself, still made sense.

Specialized use cases, like auth, can be written on top of this and that's exactly why axum-login exists.

[maxcountryman]

I can imagine a variation of this where Session is generic over T: Serialize. This would essentially translate to HashMap<String, T>. Or sessions where sessions can only contain T. So you might define a session like type UserSession = Session<User>. However, it's not clear to me how useful this is in practice. It does constrain the session to only containing values of T, but is that meaningful?

@Alxandr regarding the shape of the session, this is possible via implementing SessionStore: the SessionStore trait is a mapping from a SessionRecord to some backend. In other words, from the intermediary key-value state, which only exists in memory, to a persistence layer of your choosing. By implementing the trait, you can define how it's stored, including its precise shape.

Of course, you're also responsible for loading it back to a SessionRecord, but that's intentionally a very small surface area, containing only "expiration_time" as its singular piece of metadata.

[Alxandr]

Yeah, but I still have to actually have a hashmap, which feels wasteful and error-prone for my use-case. Suddenly there is the possibility for writing keys wrong for instance. In general, it's introducing a string-based API where none is needed. Though, this might just mean that this library isn't for me.

I would have a hard think about the use-case of well-defined session structs. I would imagine quite a few applications would be happy defining a struct SessionData (with whatever fields it has), and a SessionStorage<SessionData>, as opposed to having a "bag of data" type. This makes change-tracking harder (it could be done on either the storage trait or a session-type trait, but still it can't probably be general) - but I still think it's worth it.

Then a "bag of data" session-data can be implemented on top as a simple solution for when you really just want to serialize/deserialize some strings into your session-storage.

[maxcountryman]

@Alxandr sessions are almost always key-value stores. So we might not be talking about a "session" at this point, but something else entirely. For example, if your session is any T, then we have to worry about how to implement insert, get, delete, etc--this starts to become more complex and that complexity will either end up in the crate or worse yet with the user.

But again, you can quite easily build what you're describing on top of a key-value model.

At the end of the day, your Rust type is going to be serialized to some other representation if you intend for it to persist apart from your Rust program. We can certainly generalize serde_json::Value, assuming that's useful, but I'm again unclear where this would come in particularly handy.

I would also pushback a bit on the idea that HashMap<String, Value> is "stringly" typed: JSON isn't my favorite representation, but it's quite a bit better than just a string. 🙂 (I would also say, I'm happy to consider other representations if that's a real issue for folks; I don't love JSON, but it's convenient and seems like a relatively unimportant implementation detail at this point.)

Suddenly there is the possibility for writing keys wrong

This seems like an unwarranted concern. Why is this a danger if you know your type? Even more so in the case where Session might be constrained to a particular T: if you only write T you can't mess this up and Rust will do a good job of making sure you don't make that particular error.

The benefit of using HashMap is you get a nice interface over the intermediate representation and because we ask for impl Serialize with insert and get returns T: DerserializeOwned you also get arbitrary Rust types with minimal constraints.

[Alxandr]

sessions are almost always key-value stores. So we might not be talking about a "session" at this point,

this is the part I don't agree with though - which is why I ended up creating my own implementation.

[benwis]

I haven't checked the code yet, but would it be possible to disable the creation of new sessions if no cookie is present? Seems like unecessary overhead for parts of the app that don't need that funcionality

[maxcountryman]

While I understand the impulse to eliminate perceived overhead, it's hard to see how this would be possible.

Consider that we have no way of knowing when an extension will be used and in order to provide the extension on the request, we must create the session.

Perhaps we could imagine making the request extension Optional<Session>. While this is tempting, it would create a more awkward interface, requiring consumers to first check that the session exists in their handlers. It also wouldn't solve a related problem.

Sessions are used to create the cookie, so without a session, we aren't able to create the cookie in the first place.

That said, I think the additional overhead here is minimal and nonexistent between the client and server (we create a Session in the service, but we don't set a cookie until the session has been used, i.e. via insert).

[benwis]

I think that's fair, however I can tell you that if/when you add something like db backed sessions, it will cause a significant performance hit. We went through that with the other sessions crate

[maxcountryman]

if/when you add something like db backed sessions, it will cause a significant performance hit.

I don't see how this can be the case: if there's no cookie, the store isn't invoked. Creating a session itself does not involve the store until it's inserted into and only then is it saved back to the store. In other words, the store isn't used until you use the session in some material way.

How would we avoid the overhead of loading a session when we do have a cookie? It's true that's a cost, but it's kind of the point of this crate. 🙂

[benwis]

It depends on the structure. It created a session and stored it for every visit to the page, regardless of whether a cookie existed or not. Which put the db under contention. I think we're on the same page here, and you'll avoid this, so thank you! :)

[maxcountryman]

It's worth taking a look at the business logic within the service itself. Both because that's illustrative of the constraints we're working with but also because it helps make the potential overhead more concrete.

If you have ideas for further optimizations, I'm more than happy to consider and incorporate those. 😃

[dsaghliani]

Sounds exciting!

Sessions can be added directly to requests as extensions without the need for two extractors (internally they use a Mutex around their shared mutable state).

Wouldn't this make them effectively single-threaded? No two routes could access the session data at the same time, even if they need read-only access (which is the case for auth). A RwLock is usually used in this situation. This bears benchmarking.

[maxcountryman]

Wouldn't this make them effectively single-threaded?

That's correct. I'm open to using a RwLock: we're wrapping the lock with our API, so it wouldn't be too difficult to make that transparent. At the same, we minimize the time we hold the lock by acquiring it immediately before an operation over the underlying hash map. For example, in insert: https://github.com/maxcountryman/tower-sessions/blob/861111154c9db66e66872d5eb8348bd2692fb71b/src/session.rs#L116

[dsaghliani]

That makes sense now. I like not leaking implementation details into the public API.

Maybe we could even experiment with message-passing to see how it performs. I remember this video comparing Rust and Go servers, where the Rust one used a mutex while the Go server, as always, did message-passing, and Go dominated. I'm sure Rust would've performed way better with a RwLock, but maybe message-passing is faster still.

dashmap is another option.

[maxcountryman]

I'm confident there's room for improvement here and I suspect the biggest improvements wouldn't require changing the user-facing API.

Regarding message passing, I wondered about mpsc but didn't spend the time experimenting. Dashmap seems like it could also be a good candidate, but again a Mutex wrapping Inner was the simplest immediate approach.

At any rate, I'm more than happy to incorporate optimizations and ideally we'll quantify their impact before deciding on the best direction.

[Alxandr]

One of the reasons I ended up rolling my own session management code for a pet project of mine is the fact that axum-session prescribed the "shape" of the session for me - that is, a hashmap. In my usecase, sessions are well-defined in what properties they have, and maps directly to a database table (https://github.com/Alxandr/dbost/blob/be07185/domain/entities/src/session.rs#L15).

[maxcountryman]

I don't see how HashMap<String, T> is any better than T.

It's difficult to have a conversation when you reject the idea that sessions are commonly key-value interfaces. I'm really not sure where we can go from there. (I did look, but I couldn't immediately find any counter examples--I very possibly missed something, but my takeaway is that sessions are well-known to manage key-value pairs and most folks coming to this crate with prior experience will be expecting to find that).

If you can follow me here for just a bit, my point is that this is a crate that delivers sessions. What you're describing seems to make sense for your project but is also distinct from the general notion of what a session is.

I understand that might not be what you want to hear and I would also point out I'm not saying that to invalidate the pattern you've used: there's absolutely nothing wrong with it. However, it is important to be clear that my aim is specifically toward sessions and not a different interface for associating data with users.

Lastly I'm still not convinced of the objections here. Consider that you can define types for your keys (!): const USER_ID_KEY: &str = "user_id";. I worry that the objection is mostly theoretical at this point and more deeply rooted in aesthetics than anything else.

[maxcountryman]

Why am I serializing my session object?

Do you have thoughts on how you'd support arbitrary backends?

When you only have a specific backend, I agree: you can skip this step. However, when you don't know what your storage backend is, you need some way of translating your Rust into a representation that will be acceptable virtually anywhere.

It's also worth pointing out here that if you for example use a database, you are serializing even if it's a little less visible thanks to the driver handling this transparently. (Yes, there's two phases of serialization in our case; this can be avoided in cases where e.g. JSON is a native type.)

Similarly when you read from your storage layer.

Is there overhead in our implementation. Absolutely. It's not entirely free. You can avoid some of this overhead by building a solution that's coupled tightly to your system. That said, we're trying to be thoughtful about minimizing this overhead (within the scope of certain goals).

I also want to share an important bit of context (and I apologize, I really should have mentioned this earlier): one of the primary drivers for me here is optimizing for utility. To that end, it may be helpful to know (and this surprised to me learn) that axum-sessions has over 100,000 downloads on crates.io, with over half of those being recent--in other words, that trend seems to be growing.

I mention this because for better or worse, folks seem to be finding utility with the interface. This doesn't mean it's perfect by any means whatsoever, but it is an important piece of input to the design, especially if tower-sessions will replace axum-sessions.

There is so much unnecessary work going on here, and it's the reason I didn't use axum-session last time.

I would like to thank you for your feedback here--sometimes it can feel like feedback is not helpful if it doesn't lead to a specific outcome, but objectively it is helpful for me and I appreciate it.

[maxcountryman]

Also I wanted to mention typed-session, which largely provides what I think you want. If you do build your own crate for user-associated data over cookies, you might have a look at this.

I don't think it's a good fit for tower-sessions for the reasons already discussed and at this point, I won't be relying on a third-party crate for session functionality.

[Alxandr]

sessions are well-known to manage key-value pairs

To me, sessions (in a web server context) is any server-state that's tied to a user "session" (typically keyed by a cookie). A hashmap/bag of data is just how most frameworks has chosen to implement this. My guess is that this is either because they are dynamic languages, because it makes the interface for storage backends easier, or because they've just though "that's just what sessions are." But that's mostly speculation.

The sad part to me is that there are some cross-cutting concerns between what I see as a session, and what this library provides. My point is that a hashmap is a kind of session. It's just not the only kind. The parts that are identical (and is what I would call session management) is:

1. validating and (optionally?) decrypting the session-id cookie.
2. checking that the session cookie is not expired
3. asking a storage backend for the session by id (or a new one if no cookie existed)
4. setting request extensions so rest of application can read the session
5. after rest of the tower stack has ran, checking if the session has been modified (or flagged for deletion)
6. telling the storage backend to update it's sliding window maybe? This might belong in point 3.
7. telling the storage backend to update it's data. This is probably merged with 6.
8. Encrypting (optionally?) and signing a new session-id cookie if it needs to be created/updated.

I hope you can see that there's quite a bit of common functionality here, which is why I'm interested in a good session library. Cause one that's used by more people is probably less likely to have bugs than one I just wrote myself.

Lastly I'm still not convinced of the objections here. Consider that you can define types for your keys (!): const USER_ID_KEY: &str = "user_id";. I worry that the objection is mostly theoretical at this point and more deeply rooted in aesthetics than anything else.

To me, this feels about as weird as saying that we should make everything HashMap<String, Box<dyn Any>> cause it's convenient. I find it really weird why anyone would use a HashMap when they don't need one, especially if it involves serializing and deserializing as a technical limitation because a map was chosen as the session storage.

It's also worth pointing out here that if you for example use a database, you are serializing even if it's a little less visible thanks to the driver handling this transparently. (Yes, there's two phases of serialization in our case; this can be avoided in cases where e.g. JSON is a native type.)

Yes, ofcause, I know this. I'm just talking about this extra set of serialization/deserialization. But this also means I can't have "state" in my session object. Like for instance, I can't have my own change-tracking in the session, because everything get's copied everywhere. SeaOrm for instance represents an active record as a struct with fields of an enum type, where the variants represents if the field has been updated or not. If I want to change one of the fields with it being serialized as a string (assuming it's serializable at all) would mean I have to deserialize, make changes, reserialize and then put it back into the map. This also introduces potential race-conditions I imagine, unless the lock is held the whole time I am manipulating the deserialized data.

I also want to share an important bit of context (and I apologize, I really should have mentioned this earlier): one of the primary drivers for me here is optimizing for utility. To that end, it may be helpful to know (and this surprised to me learn) that axum-sessions has over 100,000 downloads on crates.io, with over half of those being recent--in other words, that trend seems to be growing.

This I completely get, and can completely agree with. But it's also why I'm really hoping for a layered API. Where there is a simple, high level API which gives you a map, and is good enough for most people, because most people don't care. But I would really like some of the building-blocks of that API to also be exposed as a more low-level API, which would give you typed sessions.

Also I wanted to mention typed-session, which largely provides what I think you want. If you do build your own crate for user-associated data over cookies, you might have a look at this.

This seems interesting, and I will have to look at it a bit more. It might be half of what I need (minus the tower integration). It also has the storage trait defined to handle generic data, so it does show that to be possible at least. I'd also like to point you to the following section in it's documentation:

This crate was designed after async-session. The main difference is that the session data is generic, such that the user can plug in any type they want. If needed, the same HashMap<String, String> can be used as session data type.

This is exactly my case. A HashMap<String, String> session is just a special case of a session object.

I don't think it's a good fit for tower-sessions for the reasons already discussed and at this point, I won't be relying on a third-party crate for session functionality.

I can't say I agree with you, but at the end of the day it's your project, and you're free to do with it as you wish. I think we've both said our piece, and there's probably not a good reason to keep going around on this anymore. I find it really sad how session is considered to mean a key value store, and why people would give up the strong typing guarantees of rust for it when there is no need to (as opposed to cookies or similar that needs to be marshalled to the client). But if this is what you want to build, I'm not going to stop you, nor pester you for it. I'll just have to use something else, like I already am :). I will definitely be taking a look at that typed-session crate though, to see if I can offload some of my implementation to it.

[maxcountryman]

A hashmap/bag of data is just how most frameworks has chosen to implement this.

This is key. I cannot overstate the importance of this. The problem with forgoing this altogether you will risk alienating a whole bunch of folks who already understand sessions as key-value pairs associated to a site visitor.

Even Scala takes this approach (!) in the Play framework.

I'm sorry, but I just don't see how you can argue with a straight face that this isn't the common definition. You're free to think otherwise of course, but there's a cost to going against the grain and it's one I'm personally not interested in at this point.

I find it really weird why anyone would use a HashMap when they don't need one, especially if it involves serializing and deserializing as a technical limitation because a map was chosen as the session storage.

The hash map is needed. Let's turn this around: how do you present an API that allows for insert, get, remove, etc? A hash map isn't strictly speaking the only option, but it's a natural one.

Taking this a bit further, we want to target JSON because it allows us to enable SessionStore to be implemented against a vast array of backends. Could we use another representation? Yes. That said, I think JSON is more or less fine, an obvious alternative notwithstanding.

My point is that a hashmap is a kind of session. It's just not the only kind.

If there were a sustainable path to this, that avoided a dramatic increase in complexity, then I would incorporate it.

But it's also why I'm really hoping for a layered API.

I cannot stress enough how much complexity this introduces. Just have a look at typed-sessions: it's not an implementation I'm eager to adopt. It's also unclear that it provides many of the fundamental properties required for sessions, like the hash map operations, expirations, and granular modification detection.

Also please see their related project: typed-sessions-axum. This should address the axum use case if not the tower use case.

I find it really sad how session is considered to mean a key value store,

It's just the reality that this is what many people understand a session to mean. Changing this definition more broadly is not a goal I'm going to pursue with this project.

and why people would give up the strong typing guarantees of rust for it when there is no need to

Furthermore, you do not have to give up on strong typing just because you use a key-value interface. I understand you don't like the pattern, but it's unfair and disingenuous to make this claim. In fact, it's quite possible to build strongly-typed interfaces directly on top of key-value stores.

Okay last thing I have to say on this: because HashMap<String, Value> can be implemented in terms of T, the door will remain open. We'll be able to back into this in the future if someone is able to come up with a reasonable way of implementing this that doesn't compromise on the expected session interface many users will have.

[teenjuna]

@maxcountryman here is my example from a real system. Basically I have this types:

/// User session.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Session {
    pub id: Thing,
    pub user: LinkedRecord<User>,
    pub expires: DateTime,
    pub ip: Vec<String>,
    pub created_at: DateTime,
    pub updated_at: DateTime,
}

/// User of the system.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct User {
    pub id: Thing,
    pub role: UserRole,
    pub cart: Vec<LinkedRecord<CartItem>>,
    pub orders: Vec<LinkedRecord<Order>>,
    pub created_at: DateTime,
    pub updated_at: DateTime,
}

I also have a custom middleware that creates sessions with users (session always has a user). If I went with a HashMap-like session, not only wouldn't I be able to control the relation of the session and user in the database (which is important for scheduled work, like remove all sessions that are old enough and related to users that have an empty shopping cart), I would also need to implement two middlewares: one that "catches" new sessions and creates a user for them, and one that fetches the user based on a user id from a coming session. This is both less usable and less performant.