/ 
GraphQL-Houtou-0.01
/ GraphQL::Houtou::Runtime::NativeRuntime

NAME

GraphQL::Houtou::Runtime::NativeRuntime - request-time execution API on the XS VM

SYNOPSIS

my $runtime = $schema->build_native_runtime(async => 1);

# dynamic queries (program compiled + cached per query string)
my $result = $runtime->execute_document($query, variables => \%vars);
my $bytes  = $runtime->execute_document_to_json($query, variables => \%vars);

# persisted artifacts
my $program = $runtime->compile_program($query);
my $result  = $runtime->execute_program($program, variables => \%vars);
my $result  = $runtime->execute_bundle($bundle);
my $bytes   = $runtime->execute_bundle_to_json($bundle);

DESCRIPTION

The reusable execution engine built from a schema by build_native_runtime. Build it once at startup; every method here is request-time API. Queries compile into native programs (cached per query string, FIFO, program_cache_max, default 1000) and execute on the XS VM. See "API Selection Guide" in GraphQL::Houtou for choosing between documents, programs, and bundles.

EXECUTION METHODS

execute_document($query, %opts) / execute_document_to_json($query, %opts)

Compile (or fetch from the program cache) and execute. The _to_json form renders UTF-8 JSON bytes directly from the XS lane without building the Perl envelope. Options:

  • variables - hashref of GraphQL variable values

  • operation_name - selects the named operation from a multi-operation document (the compiler otherwise executes the first one). Programs cache under a (document, operation_name) key, so repeated requests naming an operation stay on the hot path. An unknown name is a request error (errors-only envelope).

  • context / root_value - passed to resolvers

  • allow_introspection - defaults to true. Set false on the runtime or per request to reject __schema and __type with the INTROSPECTION_DISABLED request-error code. __typename remains available. The policy check is cached with the compiled document and cannot be bypassed with validate => 0.

  • on_stall - stall-flush hook; the request runs on the async-capable lane and is driven to completion synchronously (see "Batching resolvers (DataLoader / the on_stall hook)" in GraphQL::Houtou)

  • strict_sync - set true to force the strict sync fast lane even on an async runtime; promise resolvers croak there. Omit it for normal automatic lane selection. Execution always uses the XS native runtime.

execute_program($program, %opts) / execute_program_to_json($program, %opts)

Execute a program compiled with compile_program($query). Same options as above; this is the persisted-query path for variable-bearing queries. Programs and bundles are trusted prevalidated artifacts, so the allow_introspection document policy is enforced while accepting dynamic documents, not while executing these direct artifact APIs.

execute_bundle($bundle, %opts) / execute_bundle_to_json($bundle, %opts) / execute_bundle_descriptor($descriptor, %opts)

Execute a fixed-query native bundle (no GraphQL variables; argument values are baked in at compile time). Descriptors are the serialisable form for crossing process boundaries.

LANE SELECTION

Requests choose an execution lane automatically: on_stall or a runtime built with async => 1 starts on the async-capable lane (promises suspend and resume); otherwise requests run the synchronous fast lane and promise-returning resolvers fail with an error naming both fixes.

OTHER METHODS

compile_program, compile_bundle, descriptor dump/load pairs (dump_bundle_descriptor / load_bundle_descriptor and friends), program_cache_size, clear_program_cache, runtime_schema.

SEE ALSO

GraphQL::Houtou, GraphQL::Houtou::Schema, GraphQL::Houtou::DataLoader