feat(backend,clerk-js,shared): Introduce suffixed / un-suffixed cookies

[dimkl]

Description

Introduce suffixed / un-suffixed cookies to support multiple apps in the same domain.

TODOs

• add integration test
• add tests

Checklist

• npm test runs as expected.
• npm run build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: e73b3a2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 13 packages

Name	Type
@clerk/clerk-js	Minor
@clerk/backend	Minor
@clerk/shared	Minor
@clerk/chrome-extension	Patch
@clerk/clerk-expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/remix	Patch
@clerk/clerk-sdk-node	Patch
@clerk/elements	Patch
@clerk/clerk-react	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[changeset-bot]

🦋 Changeset detected

Latest commit: ec9b127

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@clerk/clerk-js	Minor
@clerk/backend	Minor
@clerk/shared	Minor
@clerk/chrome-extension	Patch
@clerk/clerk-expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/remix	Patch
@clerk/clerk-sdk-node	Patch
@clerk/clerk-react	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[BRKalow]

🤔 Instead of introducing this Pipeline primitive, can we create some sort of cookies abstraction that handles dealing with the suffix?

This isn't a pattern we have elsewhere and I'm finding myself having to jump to the Pipeline definition to understand what's happening here. If we want to keep this abstraction, some comments might help explaining how it works.

[BRKalow]

If we're going to introduce these new functional primitives, can we make sure they're clearly documented?

[dimkl]

If we are going to introduce them i will add JSDoc with examples for each primitive :)

[nikosdouvlis]

Why do we define the pipeline here instead of closer to where we call it? Is it used by something in between?

[nikosdouvlis]

What would be the alternative way to write this without pipelines?

[nikosdouvlis]

I'm trying to understand the pattern used here but I do need to do some more reading. This, however, looks like we're simply chaining methods while keeping a reference to their return value. Is this simply it?

[dimkl]

The Pipeline pattern is a mix of 2 more commonly known patterns:

• Chain of Responsibility
• Command

This, however, looks like we're simply chaining methods while keeping a reference to their return value.

(kind of) yes.

Article about Pipeline pattern: https://medium.com/@bonnotguillaume/software-architecture-the-pipeline-design-pattern-from-zero-to-hero-b5c43d8a4e60

[nikosdouvlis]

(This looks like the missing interface I was talking about in #3362)

This feels a little too complicated to me because it looks like we're defining 4 interfaces (and some duplicates across this PR and #3362 ) to simply invoke 2 methods. However, I want to think more about it as I'm not familiar with the pattern.

Could we achieve the same results by defining a method/helper with the following signature?

function writeCookie(handlers: CookieHandler[]) {
  handlers.forEach(h => h.write(...))
}

or similar? Would that be simpler?

[dimkl]

This PR handles both generating multiple values based on a single input (case of backend SDK that uses a single cookie directive and produces the suffixed and un-suffixed variants) and performing multiple actions triggering a single pipeline method (eg write both suffixed and un-suffixed cookies using a single cookie key and value).
That's why there are multiple interfaces that look similar.
To achieve the same using method / helpers we should:

• write 3 cookie handlers (eg session, clientUat, devBrowser) for ClerkJS
• write 3 functions to generate the cookie key variants (eg session, clientUat, devBrowser) for backend SDK

For me this seems like the same amount of class or methods but different implementation. Using a pattern (even though it would require some time to learn it) would make the handling of all those cases consistent and expected instead of trying to read and verify what it's separate handler or function does.
If you think that it's more complex than it should, let's drop the pattern usage and simplify things. @nikosdouvlis Feel free to provide any suggestion on how we could make things simpler?

[dimkl]

Would you consider this example of implementing the same pattern more readable and preferrable?

//
// @clerk/shared
//
type Operation<T> = (...args: any[]) => T;
const pipeline = <T>(operations: Operation<T>[], ...args: any[]) =>
  operations.map((o) => o(...args)).find(Boolean);

//
// @clerk/backend
//
const getCookieSuffixFromPk = (publishableKey: string): string => {
  return publishableKey.split("_").pop() || "";
};

const unSuffixCookie = (publishableKey: string) => {
  return (cookieDirective: string) => {
    //...
  };
};

const suffixCookie = (publishableKey: string) => {
  return (cookieDirective: string) => {
    //...
  };
};

// Example of executing the pipeline

const cookieDirectives = ["__session=aloha"];
cookieDirectives.map((cookieDirective) =>
  pipeline(
    [suffixCookie("pk_test_"), unSuffixCookie("pk_test_")],
    cookieDirective
  )
);

//
// @clerk/clerk-js
//

import { createCookieHandler } from "@clerk/shared/cookie";

const getCookie = () => {
  return (cookieName: string) => {
    //...
  };
};

const getSuffixedCookie = (publishableKey: string) => {
  return (cookieName: string) => {
    //...
  };
};

// Operations

const setCookie = () => {
  return (cookieName: string, value: string) => {
    //...
  };
};

const setSuffixedCookie = (publishableKey: string) => {
  return (cookieName: string, value: string) => {
    //...
  };
};

const removeCookie = () => {
  return (cookieName: string, value: string) => {
    //...
  };
};

const removeSuffixedCookie = (publishableKey: string) => {
  return (cookieName: string, value: string) => {
    //...
  };
};

// pipelines

const getPipeline = (cookieName: string) =>
  pipeline([getCookie(), getSuffixedCookie("pk_test_")], cookieName);
const setPipeline = (cookieName: string, value: string) =>
  pipeline([setCookie(), setSuffixedCookie("pk_test_")], cookieName, value);
const removePipeline = (cookieName: string) =>
  pipeline([removeCookie(), removeSuffixedCookie("pk_test_")], cookieName);

// Example of executing the pipeline

getPipeline("__session");
setPipeline("__session", "value");
removePipeline("__session");

cc: @BRKalow , @nikosdouvlis