Skip to content

Latest commit

 

History

History
238 lines (174 loc) · 11.7 KB

anonymous.md

File metadata and controls

238 lines (174 loc) · 11.7 KB

Guest sessions

You will let a visitor use the app before they have said who they are: a cart, a trial, a draft, kept under a guest session. When the guest signs up or signs in, by any method, your hook moves their data to the real account inside the same transaction, and the guest row is deleted. A guest is an ordinary user with no identifier, so your tables that reference a user work for a guest unchanged.

Use this plugin for trial-before-sign-up and cart hand-over, where asking for an address first costs you the visitor.

Before you start

  • An app with at least one real sign-in method wired, as in your first app: the guest must have something to become.
  • The example program this guide is built from, with a main_test.go that drives the same steps and a README.md with the same transcript: examples/guest-sessions.
  • The reference for every option, route and error is the package's README.

Step 1 — Wire the plugin with your link hook

The example wires email, passwords and guests. OnLink is the one line the app adds:

newAuth · examples/guest-sessions/main.go:115-126

func newAuth(db *sql.DB, m email.Mailer) (*auth.Auth, error) {
	return auth.New(
		auth.WithDB(db, sqlb.SQLiteDialect{}),
		auth.WithBaseURL(baseURL),
		auth.WithPlugins(
			email.New(email.Login(), email.Recover(), email.WithMailer(m)),
			password.New(),
			anonymous.New(anonymous.OnLink(moveCart)),
		),
		auth.WithDataHooks(auth.DataHooks{User: auth.TableHooks[auth.User]{BeforeDelete: deleteCart}}),
	)
}

The hook receives the guest and the account, and the transaction the sign-in runs in. It moves the app's rows; the plugin deletes the guest right after it returns. An error fails the sign-in and leaves the guest as it was, so a cart is never lost half way:

moveCart · examples/guest-sessions/main.go:133-136

func moveCart(ctx context.Context, tx sqlb.DBTX, guest, user auth.User) error {
	_, err := tx.ExecContext(ctx, "UPDATE app_cart_item SET user_id = ? WHERE user_id = ?", user.ID, guest.ID)
	return err
}

LinkFunc · plugin/anonymous/anonymous.go:99

type LinkFunc func(ctx context.Context, tx sqlb.DBTX, guest, user auth.User) error

The cart table is an ordinary app table holding a user id, with no foreign key (the library creates none); the app's User.BeforeDelete hook removes a deleted user's cart, which is why the move has to run first:

cartSchema · examples/guest-sessions/main.go:72-75

`CREATE TABLE IF NOT EXISTS app_cart_item (
	user_id TEXT NOT NULL,
	item TEXT NOT NULL
)`

The plugin adds one column to auth_user, is_anonymous, through its own migration; a.Migrate creates it with everything else.

Check: go run ./guest-sessions prints listening on http://localhost:8081, and GET /cart answers 401 to a visitor with no session.

Step 2 — Start a guest session

sign-in takes no identifier. It creates a user named Guest (WithName changes how the name is made) and starts a session:

O='Origin: http://localhost:8081'
curl -s -c cookies.txt -X POST localhost:8081/auth/anonymous/sign-in -H "$O" -d '{}'
{"user":{"id":"usr_jvptwzit6fqupar25t5yklu5","name":"Guest","image":""}}

The cart handler asks only for a signed-in user (authhttp.RequireUser), so it works for the guest:

curl -s -b cookies.txt -X POST localhost:8081/cart -H "$O" -d '{"item":"lamp"}'
curl -s -b cookies.txt -X POST localhost:8081/cart -H "$O" -d '{"item":"chair"}'
{"userId":"usr_jvptwzit6fqupar25t5yklu5","items":["lamp"]}
{"userId":"usr_jvptwzit6fqupar25t5yklu5","items":["lamp","chair"]}

From Go:

Plugin.SignIn · plugin/anonymous/anonymous.go:338-340

func (p *Plugin) SignIn(ctx context.Context) (SignInResult, error) {
	return p.signIn.Call(ctx, SignInRequest{})
}

SignInResult · plugin/anonymous/anonymous.go:329-332

type SignInResult struct {
	User  auth.UserView `json:"user"`
	Token auth.Token    `json:"-"`
}

Check: a guest asking for another guest session is refused, so a page that reloads cannot pile up guest rows. Guest creation is limited to 10 per IP per hour (WithSignInLimit):

curl -s -b cookies.txt -X POST localhost:8081/auth/anonymous/sign-in -H "$O" -d '{}'
{"error":{"code":"anonymous.already","message":"You already have a guest session."}}

Step 3 — The guest signs up, and the cart follows

The sign-up runs with the guest's cookie. Every sign-in method ends by creating a session, and that is where the plugin's hook runs: the request's user is the guest, the new session's user is the account. Your OnLink moves the cart, the guest is deleted, and the new session replaces the cookie:

curl -s -b cookies.txt -c cookies.txt -X POST localhost:8081/auth/password/sign-up -H "$O" \
  -d '{"identifier":"alice@example.com","password":"correct horse battery","name":"Alice"}'
curl -s -b cookies.txt localhost:8081/cart
{"user":{"id":"usr_uaheceq3wu6wxfh4hsayj2sd","name":"Alice","image":""},"verificationRequired":false,"secondFactorRequired":false}
{"userId":"usr_uaheceq3wu6wxfh4hsayj2sd","items":["lamp","chair"]}

The same happens when a guest signs in to an existing account: with a password, a magic link, an emailed or texted code, a social provider, a passkey, or a method you add later. Nothing links for a session of the same user, for an admin's impersonation, or for a request that carries no guest.

Check: a.User(ctx, guestID) answers auth.user_not_found once the link ran, and an.IsAnonymous(ctx, userID) answers false for the account.

Options you may want

Option Use it when
anonymous.KeepUsers() Guest rows have value of their own. The guest stays after linking, and the delete route is not registered.
anonymous.WithName(fn) Guests need distinct names ("Visitor 4812").
anonymous.SweepStale() Guests who never signed up should go away: a.Sweep deletes guests older than the retention whose every session has expired. Off by default, because deleting a user runs your BeforeDelete hook over its rows.
anonymous.WithSignInLimit(n, window) Another limit on guest creation per IP.

A guest may delete their own account with POST /anonymous/delete; a real account is refused:

Plugin.Delete · plugin/anonymous/anonymous.go:346-349

func (p *Plugin) Delete(ctx context.Context) error {
	_, err := p.remove.Call(ctx, struct{}{})
	return err
}

A guest who adds and verifies an address or number of their own stops being a guest: the flag clears, and a later sign-in to another account no longer links them away. That is the other way out of guest status, for an app whose settings page lets a guest add an email.

From TypeScript

Use this when a browser or app page lets a visitor start before signing up: a cart, a draft, a trial. The typed client has the two routes as client.anonymous.signIn and client.anonymous.delete; list anonymous() in plugins with the sign-up methods the guest will use later.

Start a guest session, then sign up in the same browser. Nothing else is called: the sign-up's session creation runs the server's OnLink, which moves the guest's data and deletes the guest:

guestThenAccount · clients/ts/examples/plugin-signin.ts:27-33

export async function guestThenAccount(address: string, secret: string): Promise<string | null> {
  const guest = await auth.anonymous.signIn();
  if (guest.error && guest.error.code !== "anonymous.already") return null;
  // ... the guest fills a cart ...
  const account = await auth.password.signUp({ identifier: address, password: secret });
  return account.data?.user.id ?? null;
}

A guest who leaves can delete the guest account:

leaveAsGuest · clients/ts/examples/plugin-signin.ts:38-41

export async function leaveAsGuest(): Promise<boolean> {
  const { error } = await auth.anonymous.delete();
  return error === null;
}

The codes a frontend handles: anonymous.already when the browser already has a guest session (keep using it; a page that calls signIn on every load meets this), anonymous.not_anonymous from delete on a real account, auth.rate_limited (guest creation is limited per IP). The rest is in What can go wrong.

There is no runnable TypeScript example for guests yet; the blocks above are type-checked by task ts:check, and Steps 2 and 3 show the same calls with curl.

Pitfalls:

  • The upgrade must happen in the browser that holds the guest session. The link runs because the sign-up request carries the guest's cookie (or bearer token); a sign-up from another device starts a fresh account and the guest's data stays behind.
  • Call signIn once, not on every page load. Read client.session() first; a guest is signed in like anyone else, with the name Guest by default.

Every method with its route and types: TypeScript client reference › anonymous.

What can go wrong

Error When Fix
anonymous.already (409, "You already have a guest session.") A guest called sign-in again. Use the session you have; the client should not ask twice.
anonymous.not_anonymous (403, "This is not a guest account.") A real account called delete. Account deletion for real users is the app's own feature (a.DeleteUser).
auth.rate_limited (429) More than 10 guests from one IP in an hour. Wait, or raise WithSignInLimit behind a shared NAT.
The sign-in fails with your own error OnLink returned it. The guest is untouched; fix the move and let the user try again.
The cart is gone after sign-up No OnLink, and the app's BeforeDelete hook deleted the guest's cart with the guest. Add OnLink, or KeepUsers().

Known limits:

  • A guest session is a cookie: whoever holds the device holds the cart.
  • The link runs on session creation. A sign-in that issues no session (a sign-up that still needs verification) links nothing yet; the link runs when the person signs in afterwards from the same guest session.

Next

  • Sessions: what a guest session is, and the "remember me" choice sign-in accepts.
  • Hooks: the data hook mechanism this plugin is built on.
  • The package README is the full reference; the Go reference is on pkg.go.dev.