feat: add single player mode

packages/lib/server-only/feature-flags/all.ts

@@ -0,0 +1,39 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { getToken } from 'next-auth/jwt';
+
+import { LOCAL_FEATURE_FLAGS } from '@documenso/lib/constants/feature-flags';
+import PostHogServerClient from '@documenso/lib/server-only/feature-flags/get-post-hog-server-client';
+
+import { extractDistinctUserId, mapJwtToFlagProperties } from './get';
+
+/**
+ * Get all the evaluated feature flags based on the current user if possible.
+ */
+export default async function handlerFeatureFlagAll(req: Request) {
+  const requestHeaders = Object.fromEntries(req.headers.entries());
+
+  const nextReq = new NextRequest(req, {
+    headers: requestHeaders,
+  });
+
+  const token = await getToken({ req: nextReq });
+
+  const postHog = PostHogServerClient();
+
+  // Return the local feature flags if PostHog is not enabled, true by default.
+  // The front end should not call this API if PostHog is not enabled to reduce network requests.
+  if (!postHog) {
+    return NextResponse.json(LOCAL_FEATURE_FLAGS);
+  }
+
+  const distinctId = extractDistinctUserId(token, nextReq);
+
+  const featureFlags = await postHog.getAllFlags(distinctId, mapJwtToFlagProperties(token));
+
+  const res = NextResponse.json(featureFlags);
+
+  res.headers.set('Cache-Control', 'public, s-maxage=60, stale-while-revalidate=300');
+
+  return res;
+}

packages/lib/server-only/feature-flags/get-asset-buffer.ts

@@ -0,0 +1,14 @@
+/**
+ * getAssetBuffer is used to retrieve array buffers for various assets
+ * that are hosted in the `public` folder.
+ *
+ * This exists due to a breakage with `import.meta.url` imports and open graph images,
+ * once we can identify a fix for this, we can remove this helper.
+ *
+ * @param path The path to the asset, relative to the `public` folder.
+ */
+export const getAssetBuffer = async (path: string) => {
+  const baseUrl = process.env.NEXT_PUBLIC_WEBAPP_URL || 'http://localhost:3000';
+
+  return fetch(new URL(path, baseUrl)).then(async (res) => res.arrayBuffer());
+};

packages/lib/server-only/feature-flags/get-post-hog-server-client.ts

@@ -0,0 +1,16 @@
+import { PostHog } from 'posthog-node';
+
+import { extractPostHogConfig } from '@documenso/lib/constants/feature-flags';
+
+export default function PostHogServerClient() {
+  const postHogConfig = extractPostHogConfig();
+
+  if (!postHogConfig) {
+    return null;
+  }
+
+  return new PostHog(postHogConfig.key, {
+    host: postHogConfig.host,
+    fetch: async (...args) => fetch(...args),
+  });
+}

packages/lib/server-only/feature-flags/get-server-component-feature-flag.ts

@@ -0,0 +1,26 @@
+import { headers } from 'next/headers';
+
+import { getAllFlags, getFlag } from '@documenso/lib/universal/get-feature-flag';
+
+/**
+ * Evaluate whether a flag is enabled for the current user in a server component.
+ *
+ * @param flag The flag to evaluate.
+ * @returns Whether the flag is enabled, or the variant value of the flag.
+ */
+export const getServerComponentFlag = async (flag: string) => {
+  return await getFlag(flag, {
+    requestHeaders: Object.fromEntries(headers().entries()),
+  });
+};
+
+/**
+ * Get all feature flags for the current user from a server component.
+ *
+ * @returns A record of flags and their values for the user derived from the headers.
+ */
+export const getServerComponentAllFlags = async () => {
+  return await getAllFlags({
+    requestHeaders: Object.fromEntries(headers().entries()),
+  });
+};

packages/lib/server-only/feature-flags/get.ts

@@ -0,0 +1,117 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { nanoid } from 'nanoid';
+import { JWT, getToken } from 'next-auth/jwt';
+
+import { LOCAL_FEATURE_FLAGS, extractPostHogConfig } from '@documenso/lib/constants/feature-flags';
+import PostHogServerClient from '@documenso/lib/server-only/feature-flags/get-post-hog-server-client';
+
+/**
+ * Evaluate a single feature flag based on the current user if possible.
+ *
+ * @param req The request with a query parameter `flag`. Example request URL: /api/feature-flag/get?flag=flag-name
+ * @returns A Response with the feature flag value.
+ */
+export default async function handleFeatureFlagGet(req: Request) {
+  const { searchParams } = new URL(req.url ?? '');
+  const flag = searchParams.get('flag');
+
+  const requestHeaders = Object.fromEntries(req.headers.entries());
+
+  const nextReq = new NextRequest(req, {
+    headers: requestHeaders,
+  });
+
+  const token = await getToken({ req: nextReq });
+
+  if (!flag) {
+    return NextResponse.json(
+      {
+        error: 'Missing flag query parameter.',
+      },
+      {
+        status: 400,
+        headers: {
+          'content-type': 'application/json',
+        },
+      },
+    );
+  }
+
+  const postHog = PostHogServerClient();
+
+  // Return the local feature flags if PostHog is not enabled, true by default.
+  // The front end should not call this API if PostHog is disabled to reduce network requests.
+  if (!postHog) {
+    return NextResponse.json(LOCAL_FEATURE_FLAGS[flag] ?? true);
+  }
+
+  const distinctId = extractDistinctUserId(token, nextReq);
+
+  const featureFlag = await postHog.getFeatureFlag(flag, distinctId, mapJwtToFlagProperties(token));
+
+  const res = NextResponse.json(featureFlag);
+
+  res.headers.set('Cache-Control', 'public, s-maxage=60, stale-while-revalidate=300');
+
+  return res;
+}
+
+/**
+ * Map a JWT to properties which are consumed by PostHog to evaluate feature flags.
+ *
+ * @param jwt The JWT of the current user.
+ * @returns A map of properties which are consumed by PostHog.
+ */
+export const mapJwtToFlagProperties = (
+  jwt?: JWT | null,
+): {
+  groups?: Record<string, string>;
+  personProperties?: Record<string, string>;
+  groupProperties?: Record<string, Record<string, string>>;
+} => {
+  return {
+    personProperties: {
+      email: jwt?.email ?? '',
+    },
+    groupProperties: {
+      // Add properties to group users into different groups, such as billing plan.
+    },
+  };
+};
+
+/**
+ * Extract a distinct ID from a JWT and request.
+ *
+ * Will fallback to a random ID if no ID could be extracted from either the JWT or request.
+ *
+ * @param jwt The JWT of the current user.
+ * @param request Request potentially containing a PostHog `distinct_id` cookie.
+ * @returns A distinct user ID.
+ */
+export const extractDistinctUserId = (jwt: JWT | null, request: NextRequest): string => {
+  const config = extractPostHogConfig();
+
+  const email = jwt?.email;
+  const userId = jwt?.id.toString();
+
+  let fallbackDistinctId = nanoid();
+
+  if (config) {
+    try {
+      const postHogCookie = JSON.parse(
+        request.cookies.get(`ph_${config.key}_posthog`)?.value ?? '',
+      );
+
+      const postHogDistinctId = postHogCookie['distinct_id'];
+
+      if (typeof postHogDistinctId === 'string') {
+        fallbackDistinctId = postHogDistinctId;
+      }
+    } catch {
+      // Do nothing.
+    }
+  }
+
+  return email ?? userId ?? fallbackDistinctId;
+};