feat(@angular/ssr): add server routing configuration API

[alan-agius4]

This commit introduces a new server routing configuration API, as discussed in RFC angular/angular#56785. The new API provides several enhancements:

const serverRoutes: ServerRoute[] = [
  {
    path: '/error',
    renderMode: RenderMode.Server,
    status: 404,
    headers: {
      'Cache-Control': 'no-cache'
    }
  }
];

const serverRoutes: ServerRoute[] = [
  {
    path: '/product/:id',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      const dataService = inject(ProductService);
      const ids = await dataService.getIds(); // Assuming this returns ['1', '2', '3']
      return ids.map(id => ({ id })); // Generates paths like: [{ id: '1' }, { id: '2' }, { id: '3' }]
    }
  }
];

const serverRoutes: ServerRoute[] = [
  {
    path: '/product/:id',
    renderMode: RenderMode.Prerender,
    fallback: PrerenderFallback.Server, // Can be Server, Client, or None
    async getPrerenderParams() {
    }
  }
];

const serverRoutes: ServerRoute[] = [
  {
    path: '/product/:id',
    renderMode: RenderMode.Server,
  },
  {
    path: '/error',
    renderMode: RenderMode.Client,
  },
  {
    path: '/**',
    renderMode: RenderMode.Prerender,
  },
];

These additions aim to provide greater flexibility and control over server-side rendering configurations and prerendering behaviors.

[dgp1130]

Great stuff here @alan-agius4! Glad to see this all coming together. 😁

[dgp1130]

Question: How does runInInjectionContext handle async callbacks? getPrerenderPaths() might return a Promise. What happens for:

function getPrerenderPaths() {
  await someAsyncWork();
  const service = inject(SomeService); // Can we inject after an `await`?
}

[alan-agius4]

No, the inject needs to happen before any async work.

function getPrerenderPaths() {
  const service = inject(SomeService); // Can we inject after an `await`?
  await someAsyncWork();
}

See: https://angular.dev/api/core/runInInjectionContext#runInInjectionContext_0

[dgp1130]

Is there any precedent for Angular APIs which are naturally async but run in an injection context? This feels like an easy tripping hazard.

I guess the workaround would be to keep a reference to the injector (or inject before the await like you suggested)?

async function getPrerenderPaths() {
  const injector = inject(Injector);
  const result = await someAsyncWork();
  if (result === something) {
    injector.inject(SomethingElse);
  }
}

/cc @AndrewKushnir is this something we should be concerned about?

[alan-agius4]

Both guards and interceptors run in an injection context.

[dgp1130]

Thanks for working through this @alan-agius4! My only remaining concern is the choice of default value for PrerenderFallback, the rest I'm happy to defer to you / @AndrewKushnir. Maybe we should have a separate conversation on that point?

[AndrewKushnir]

LGTM, just a few minor comments, mostly related to error message text improvements.

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}