/ 
GraphQL-Houtou-0.01
/ GraphQL::Houtou::Federation

NAME

GraphQL::Houtou::Federation - build an Apollo Federation 2 subgraph schema

SYNOPSIS

use GraphQL::Houtou::Federation qw(build_subgraph_schema);

my $schema = build_subgraph_schema(
  $sdl,
  entity_resolvers => {
    Product => sub {
      my ($representation, $context) = @_;
      return $context->{products}->load($representation->{upc});
    },
  },
  max_representations => 100,
);

DESCRIPTION

Builds a Federation 2 subgraph schema for use behind an Apollo-compatible Gateway or Router. It adds _service, _entities, Federation scalar and directive definitions, and an entity union derived from resolvable @key applications. Gateway and supergraph composition are intentionally outside this module.

Subgraph endpoints expose schema and entity lookup facilities and should only be reachable by the trusted Router. max_representations defaults to 100 and limits work performed by one _entities field.

entity_resolvers maps each resolvable entity type to a callback. The callback receives ($representation, $context) and returns a hash reference, undef, or a Promise::XS for either. Results are emitted in representation order, so callbacks can return request-scoped DataLoader promises to batch database access.

Every representation must contain a string __typename and satisfy at least one resolvable @key declared for that type. FieldSet syntax and field paths are validated once when the schema is built. Request dispatch is a single linear pass with constant-time type lookup.

The authored SDL returned by _service.sdl is preserved verbatim. Include a Federation 2 @link application and imports in that SDL so the Router can compose it. Directive renaming through @link(as:) is not yet supported; use the standard imported directive names. Houtou validates entity keys, but semantic validation of composition directives such as @external, @requires, and @override remains the responsibility of Rover or the deployment's composition pipeline.

SECURITY

Do not expose a subgraph directly to untrusted clients. _service publishes the service SDL and _entities provides a cross-type lookup surface. Restrict network access to the Router, authenticate Router-to-subgraph requests, keep max_representations bounded, and apply the ordinary Houtou body, depth, node, cost, timeout, and rate limits.