Backend-created sessions

Use a backend-created session when the browser should not receive the full URL list or the credential used to authorize Cloud session creation.

When should the backend create the session?

• the export contains private or short-lived source URLs;
• the source list is too large or sensitive to render in the browser;
• your server must authorize each export; or
• Cloud access is tied to a secret API key.

What does the browser implement?

Pass a createSession callback instead of files and publicKey:

const job = startZip({
  strategy: 'cloud',
  zipName: 'export.zip',
  filesTotal: 50_000,
  createSession: async ({ signal, zipName, mode }) => {
    const response = await fetch('/api/exports/123/eazip-session', {
      method: 'POST',
      credentials: 'include',
      headers: { 'Content-Type': 'application/json' },
      signal,
      body: JSON.stringify({ zipName, mode }),
    });

    if (!response.ok) {
      throw new Error('Failed to create Eazip session');
    }

    return response.json();
  },
});

filesTotal is optional and only gives the UI an initial count before the first Cloud poll returns.

What must the backend return?

The endpoint creates the Cloud session using its trusted authorization and returns:

type CloudSessionHandle = {
  sessionId: string;
  clientSecret: string;
  apiBaseUrl?: string;
};

The backend owns source selection and authorization. The browser SDK owns polling, task state, resume, and download actions after it receives the handle.

What changes for resume and retry?

The session can resume after a reload using its sessionId and clientSecret. However, the original callback cannot be serialized. After a reload, start a fresh download() call instead of retrying a session-creation failure.

React applications use the same createSession option on useEazip().download() and persist a successfully created session like any other Cloud task.

See Sessions and resume and React persistence for the client lifecycle.