diff --git a/.changesets/exp_remove_js_api_schema.md b/.changesets/exp_remove_js_api_schema.md deleted file mode 100644 index f4c46d03e7..0000000000 --- a/.changesets/exp_remove_js_api_schema.md +++ /dev/null @@ -1,5 +0,0 @@ -### Enable Rust-based API schema implementation ([PR #5623](https://github.com/apollographql/router/pull/5623)) - -We have been testing the Rust-based API schema generation implementation side by side with the old JavaScript-based implementation for a few months now, and observed no difference in behaviour. Now, the Router only uses the Rust-based implementation, which is faster and more robust. - -By [@goto-bus-stop](https://github.com/goto-bus-stop) in https://github.com/apollographql/router/pull/5623 \ No newline at end of file diff --git a/.changesets/feat_geal_entity_cache_metrics.md b/.changesets/feat_geal_entity_cache_metrics.md deleted file mode 100644 index e3d365dc16..0000000000 --- a/.changesets/feat_geal_entity_cache_metrics.md +++ /dev/null @@ -1,43 +0,0 @@ -### Entity cache: convert spans and metrics to the new format ([PR #5625](https://github.com/apollographql/router/pull/5625)) - - -This converts the entity cache metrics to the new metric format and using the custom telemetry stack. - -Here is an example of configuration: - -```yaml -telemetry: - instrumentation: - instruments: - default_requirement_level: none - cache: - apollo.router.operations.entity.cache: - attributes: - entity.type: true - subgraph.name: - subgraph_name: true - supergraph.operation.name: - supergraph_operation_name: string - subgraph: - only_cache_hit_on_subgraph_products: - type: counter - value: - cache: hit - unit: hit - description: counter of subgraph request cache hit on subgraph products - condition: - all: - - eq: - - subgraph_name: true - - products - - gt: - - cache: hit - - 0 - attributes: - subgraph.name: true - supergraph.operation.name: - supergraph_operation_name: string - -``` - -By [@Geal](https://github.com/Geal) and [@bnjjj](https://github.com/bnjjj) in https://github.com/apollographql/router/pull/5625 \ No newline at end of file diff --git a/.changesets/feat_helm_existingsecretkeyrefkey.md b/.changesets/feat_helm_existingsecretkeyrefkey.md deleted file mode 100644 index fb7f979568..0000000000 --- a/.changesets/feat_helm_existingsecretkeyrefkey.md +++ /dev/null @@ -1,9 +0,0 @@ -### Provide support to control of the key name used to retrieve the secret used for APOLLO_KEY ([Issue #5661](https://github.com/apollographql/router/issues/5661)) - -The Router Helm chart currently is hardcoded to use managedFederationApiKey as the key name to use to retrieve the value -out of the referenced secretkey. Some kubernetes customers require the use of a secretStore / externalSecret, -and may be required to use a specific key name when obtaining secrets from these sources. - -This change provides the user the ability to control the name of the key to use in retrieving that value. - -By [Jon Christiansen](https://github.com/theJC) in https://github.com/apollographql/router/pull/5662 diff --git a/.changesets/feat_helm_health_check_path.md b/.changesets/feat_helm_health_check_path.md deleted file mode 100644 index 264ff0f43a..0000000000 --- a/.changesets/feat_helm_health_check_path.md +++ /dev/null @@ -1,5 +0,0 @@ -### Provide helm support for when router's health_check's default path is not being used([Issue #5652](https://github.com/apollographql/router/issues/5652)) - -When helm chart is defining the liveness and readiness check probes, if the router has been configured to use a non-default health_check path, use that rather than the default ( /health ) - -By [Jon Christiansen](https://github.com/theJC) in https://github.com/apollographql/router/pull/5653 \ No newline at end of file diff --git a/.changesets/fix_bnjjj_filter_metric_events.md b/.changesets/fix_bnjjj_filter_metric_events.md deleted file mode 100644 index 0e441eb80d..0000000000 --- a/.changesets/fix_bnjjj_filter_metric_events.md +++ /dev/null @@ -1,5 +0,0 @@ -### Don't include metric events in spans ([PR #5649](https://github.com/apollographql/router/pull/5649)) - -Previously some internal metric events were included in traces and spans. This PR remove this noise. - -By [@bnjjj](https://github.com/bnjjj) in https://github.com/apollographql/router/pull/5649 \ No newline at end of file diff --git a/.changesets/fix_bryn_datadog_exporter_span_kind.md b/.changesets/fix_bryn_datadog_exporter_span_kind.md deleted file mode 100644 index 942c5421e1..0000000000 --- a/.changesets/fix_bryn_datadog_exporter_span_kind.md +++ /dev/null @@ -1,6 +0,0 @@ -### Datadog `span.kind` now populated ([PR #5609](https://github.com/apollographql/router/pull/5609)) - -Datadog traces use `span.kind` to differentiate between different types of spans. -This change ensures that the `span.kind` is correctly populated using the Open Telemetry span kind which has a 1-2-1 mapping to those set out in [dd-trace](https://github.com/DataDog/dd-trace-go/blob/main/ddtrace/ext/span_kind.go). - -By [@BrynCooke](https://github.com/BrynCooke) in https://github.com/apollographql/router/pull/5609 diff --git a/.changesets/fix_bryn_datadog_exporter_span_metrics.md b/.changesets/fix_bryn_datadog_exporter_span_metrics.md deleted file mode 100644 index 9c3d8143b7..0000000000 --- a/.changesets/fix_bryn_datadog_exporter_span_metrics.md +++ /dev/null @@ -1,32 +0,0 @@ -### Datadog span metrics are now supported ([PR #5609](https://github.com/apollographql/router/pull/5609)) - -When using the APM view in Datadog, span metrics will be displayed for any span that was a top level span or has the `_dd.measured` flag set. - -Apollo Router now sets the `_dd.measured` flag by default for the following spans: - -* `request` -* `router` -* `supergraph` -* `subgraph` -* `subgraph_request` -* `http_request` -* `query_planning` -* `execution` -* `query_parsing` - -You can override this behaviour to enable or disable span metrics for any span by setting the `span_metrics` configuration in the Datadog exporter configuration. - -```yaml -telemetry: - exporters: - tracing: - datadog: - enabled: true - span_metrics: - # Disable span metrics for supergraph - supergraph: false - # Enable span metrics for my_custom_span - my_custom_span: true -``` - -By [@BrynCooke](https://github.com/BrynCooke) in https://github.com/apollographql/router/pull/5609 and https://github.com/apollographql/router/pull/5703 diff --git a/.changesets/fix_bryn_datadog_timeout.md b/.changesets/fix_bryn_datadog_timeout.md deleted file mode 100644 index 8aa5f959d9..0000000000 --- a/.changesets/fix_bryn_datadog_timeout.md +++ /dev/null @@ -1,12 +0,0 @@ -### Prevent Datadog timeout errors in logs ([Issue #2058](https://github.com/apollographql/router/issue/2058)) - -The telemetry Datadog exporter uses connection pooling by default. However, these pools connections are frequently closed leading to errors in the router logs. - -For example: -``` -2024-07-19T15:28:22.970360Z ERROR OpenTelemetry trace error occurred: error sending request for url (http://127.0.0.1:8126/v0.5/traces): connection error: Connection reset by peer (os error 54) -``` - -The pool timeout for the Datadog exporter is now set to 1 millisecond, which will greatly reduce the frequency that this occurs. - -By [@BrynCooke](https://github.com/BrynCooke) in https://github.com/apollographql/router/pull/5692 diff --git a/.changesets/fix_bryn_service_version.md b/.changesets/fix_bryn_service_version.md deleted file mode 100644 index dc36d77894..0000000000 --- a/.changesets/fix_bryn_service_version.md +++ /dev/null @@ -1,17 +0,0 @@ -### Allow overriding of service version ([PR #5689](https://github.com/apollographql/router/pull/5689)) - -Previously `service.version` was not overridable via yaml and was ignored. It is now possible to set this explicitly which can be useful for users producing custom builds of the Router. - -For example: -```yaml -telemetry: - exporters: - tracing: - common: - resource: - service.version: 1.0 -``` - -Overrides the version to `1.0`. - -By [@BrynCooke](https://github.com/BrynCooke) in https://github.com/apollographql/router/pull/5689 diff --git a/.changesets/fix_spawn_blocking_parser.md b/.changesets/fix_spawn_blocking_parser.md deleted file mode 100644 index 0fd442df94..0000000000 --- a/.changesets/fix_spawn_blocking_parser.md +++ /dev/null @@ -1,5 +0,0 @@ -### use spawn_blocking for query parsing & validation ([PR #5235](https://github.com/apollographql/router/pull/5235)) - -Moves query parsing and validation in a tokio blocking task to prevent all executor threads from blocking on large queries. - -By [@xuorig](https://github.com/xuorig) in https://github.com/apollographql/router/pull/5235 \ No newline at end of file diff --git a/.changesets/maint_bnjjj_entity_cache_versioning.md b/.changesets/maint_bnjjj_entity_cache_versioning.md deleted file mode 100644 index 70ef593913..0000000000 --- a/.changesets/maint_bnjjj_entity_cache_versioning.md +++ /dev/null @@ -1,6 +0,0 @@ -### Add version in the entity cache hash ([PR #5701](https://github.com/apollographql/router/pull/5701)) - -[!IMPORTANT] -If you have enabled [entity caching](https://www.apollographql.com/docs/router/configuration/entity-caching), this release changes the hashing algorithm used for the cache keys. On account of this, you should anticipate additional cache regeneration cost when updating between these versions while the new hashing algorithm comes into service. - -By [@bnjjj](https://github.com/bnjjj) in https://github.com/apollographql/router/pull/5701 \ No newline at end of file diff --git a/.changesets/maint_garypen_modify_batch_for_tracing.md b/.changesets/maint_garypen_modify_batch_for_tracing.md deleted file mode 100644 index 145fb07f40..0000000000 --- a/.changesets/maint_garypen_modify_batch_for_tracing.md +++ /dev/null @@ -1,14 +0,0 @@ -### Improve testing by avoiding cache effects and redacting tracing details ([PR #5638](https://github.com/apollographql/router/pull/5638)) - -We've had some problems with flaky tests and this PR addresses some of them. - -The router executes in parallel and concurrently. Many of our tests use snapshots to try and make assertions that functionality is continuing to work correctly. Unfortunately, concurrent/parallel execution and static snapshots don't co-operate very well. Results may appear in pseudo-random order (compared to snapshot expectations) and so tests become flaky and fail without obvious cause. - -The problem becomes particularly acute with features which are specifically designed for highly concurrent operation, such as batching. - -This set of changes addresses some of the router testing problems by: - -1. Making items in a batch test different enough that caching effects are avoided. -2. Redacting various details so that sequencing is not as much of an issue in the otel traces tests. - -By [@garypen](https://github.com/garypen) in https://github.com/apollographql/router/pull/5638 \ No newline at end of file diff --git a/.changesets/maint_garypen_rhai_update.md b/.changesets/maint_garypen_rhai_update.md deleted file mode 100644 index 7899dcec23..0000000000 --- a/.changesets/maint_garypen_rhai_update.md +++ /dev/null @@ -1,14 +0,0 @@ -### chore: Update rhai to latest release (1.19.0) ([PR #5655](https://github.com/apollographql/router/pull/5655)) - -In Rhai 1.18.0, there were changes to how exceptions within functions were created. For details see: https://github.com/rhaiscript/rhai/blob/7e0ac9d3f4da9c892ed35a211f67553a0b451218/CHANGELOG.md?plain=1#L12 - -We've modified how we handle errors raised by Rhai to comply with this change, which means error message output is affected. The change means that errors in functions will no longer document which function the error occurred in, for example: - -```diff -- "rhai execution error: 'Runtime error: I have raised an error (line 223, position 5)\nin call to function 'process_subgraph_response_string''" -+ "rhai execution error: 'Runtime error: I have raised an error (line 223, position 5)'" -``` - -Making this change allows us to keep up with the latest version (1.19.0) of Rhai. - -By [@garypen](https://github.com/garypen) in https://github.com/apollographql/router/pull/5655 diff --git a/.config/nextest.toml b/.config/nextest.toml index cff09c8ef6..9deb55fd49 100644 --- a/.config/nextest.toml +++ b/.config/nextest.toml @@ -14,28 +14,60 @@ retries = 2 filter = ''' ( binary_id(=apollo-router) & test(=axum_factory::axum_http_server_factory::tests::request_cancel_log) ) or ( binary_id(=apollo-router) & test(=axum_factory::axum_http_server_factory::tests::request_cancel_no_log) ) +or ( binary_id(=apollo-router) & test(=axum_factory::tests::cors_origin_default) ) +or ( binary_id(=apollo-router) & test(=axum_factory::tests::cors_origin_list) ) +or ( binary_id(=apollo-router) & test(=axum_factory::tests::cors_origin_regex) ) +or ( binary_id(=apollo-router) & test(=axum_factory::tests::it_answers_to_custom_endpoint) ) +or ( binary_id(=apollo-router) & test(=axum_factory::tests::it_compress_response_body) ) +or ( binary_id(=apollo-router) & test(=axum_factory::tests::response) ) +or ( binary_id(=apollo-router) & test(=axum_factory::tests::response_with_custom_endpoint) ) +or ( binary_id(=apollo-router) & test(=axum_factory::tests::response_with_custom_endpoint_wildcard) ) +or ( binary_id(=apollo-router) & test(=axum_factory::tests::response_with_custom_prefix_endpoint) ) +or ( binary_id(=apollo-router) & test(=axum_factory::tests::response_with_root_wildcard) ) or ( binary_id(=apollo-router) & test(=notification::tests::it_test_ttl) ) +or ( binary_id(=apollo-router) & test(=plugins::authentication::subgraph::test::test_credentials_provider_refresh_on_stale) ) +or ( binary_id(=apollo-router) & test(=plugins::telemetry::config_new::instruments::tests::test_instruments) ) or ( binary_id(=apollo-router) & test(=plugins::telemetry::metrics::apollo::test::apollo_metrics_enabled) ) or ( binary_id(=apollo-router) & test(=plugins::telemetry::tests::it_test_prometheus_metrics) ) +or ( binary_id(=apollo-router) & test(=router::tests::basic_event_stream_test) ) +or ( binary_id(=apollo-router) & test(=router::tests::schema_update_test) ) or ( binary_id(=apollo-router) & test(=services::subgraph_service::tests::test_subgraph_service_websocket_with_error) ) or ( binary_id(=apollo-router) & test(=uplink::license_stream::test::license_expander_claim_pause_claim) ) or ( binary_id(=apollo-router) & test(=uplink::persisted_queries_manifest_stream::test::integration_test) ) +or ( binary_id(=apollo-router) & test(=uplink::schema_stream::test::integration_test) ) or ( binary_id(=apollo-router-benchmarks) & test(=tests::test) ) +or ( binary_id(=apollo-router::apollo_otel_traces) & test(=non_defer) ) or ( binary_id(=apollo-router::apollo_otel_traces) & test(=test_batch_send_header) ) or ( binary_id(=apollo-router::apollo_otel_traces) & test(=test_batch_trace_id) ) +or ( binary_id(=apollo-router::apollo_otel_traces) & test(=test_client_name) ) +or ( binary_id(=apollo-router::apollo_otel_traces) & test(=test_client_version) ) +or ( binary_id(=apollo-router::apollo_otel_traces) & test(=test_condition_else) ) or ( binary_id(=apollo-router::apollo_otel_traces) & test(=test_condition_if) ) +or ( binary_id(=apollo-router::apollo_otel_traces) & test(=test_send_header) ) +or ( binary_id(=apollo-router::apollo_otel_traces) & test(=test_send_variable_value) ) or ( binary_id(=apollo-router::apollo_otel_traces) & test(=test_trace_id) ) or ( binary_id(=apollo-router::apollo_reports) & test(=non_defer) ) +or ( binary_id(=apollo-router::apollo_reports) & test(=test_batch_send_header) ) or ( binary_id(=apollo-router::apollo_reports) & test(=test_batch_stats) ) +or ( binary_id(=apollo-router::apollo_reports) & test(=test_batch_trace_id) ) or ( binary_id(=apollo-router::apollo_reports) & test(=test_client_name) ) or ( binary_id(=apollo-router::apollo_reports) & test(=test_client_version) ) +or ( binary_id(=apollo-router::apollo_reports) & test(=test_condition_else) ) or ( binary_id(=apollo-router::apollo_reports) & test(=test_condition_if) ) +or ( binary_id(=apollo-router::apollo_reports) & test(=test_demand_control_stats) ) +or ( binary_id(=apollo-router::apollo_reports) & test(=test_demand_control_trace) ) +or ( binary_id(=apollo-router::apollo_reports) & test(=test_demand_control_trace_batched) ) +or ( binary_id(=apollo-router::apollo_reports) & test(=test_new_field_stats) ) or ( binary_id(=apollo-router::apollo_reports) & test(=test_send_header) ) +or ( binary_id(=apollo-router::apollo_reports) & test(=test_send_variable_value) ) +or ( binary_id(=apollo-router::apollo_reports) & test(=test_stats) ) or ( binary_id(=apollo-router::apollo_reports) & test(=test_trace_id) ) or ( binary_id(=apollo-router::integration_tests) & test(=api_schema_hides_field) ) or ( binary_id(=apollo-router::integration_tests) & test(=automated_persisted_queries) ) or ( binary_id(=apollo-router::integration_tests) & test(=defer_default_variable) ) +or ( binary_id(=apollo-router::integration_tests) & test(=defer_empty_primary_response) ) or ( binary_id(=apollo-router::integration_tests) & test(=defer_path) ) +or ( binary_id(=apollo-router::integration_tests) & test(=defer_path_in_array) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::batching::it_batches_with_errors_in_multi_graph) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::batching::it_batches_with_errors_in_single_graph) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::batching::it_handles_cancelled_by_coprocessor) ) @@ -55,24 +87,46 @@ or ( binary_id(=apollo-router::integration_tests) & test(=integration::file_uplo or ( binary_id(=apollo-router::integration_tests) & test(=integration::file_upload::it_fails_with_file_count_limits) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::file_upload::it_fails_with_file_size_limit) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::file_upload::it_fails_with_no_boundary_in_multipart) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::file_upload::it_supports_compression) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::file_upload::it_supports_nested_file) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::file_upload::it_uploads_to_multiple_subgraphs) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::lifecycle::test_graceful_shutdown) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::lifecycle::test_happy) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::lifecycle::test_plugin_ordering) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::lifecycle::test_reload_config_valid) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::lifecycle::test_reload_config_with_broken_plugin) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::lifecycle::test_reload_config_with_broken_plugin_recovery) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::redis::apq) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::redis::connection_failure_blocks_startup) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::redis::entity_cache) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::redis::entity_cache_authorization) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::redis::query_planner_redis_update_defer) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::redis::query_planner_redis_update_query_fragments) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::redis::query_planner_redis_update_reuse_query_fragments) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::redis::test::connection_failure_blocks_startup) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::datadog::test_basic) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::datadog::test_resource_mapping_default) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::datadog::test_span_metrics) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::jaeger::test_decimal_trace_id) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::jaeger::test_remote_root) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::logging::test_json) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::logging::test_json_sampler_off) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::logging::test_text) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::logging::test_text_sampler_off) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::metrics::test_bad_queries) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::metrics::test_graphql_metrics) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::metrics::test_metrics_bad_query) ) +or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::metrics::test_metrics_reloading) ) or ( binary_id(=apollo-router::integration_tests) & test(=integration::telemetry::metrics::test_subgraph_auth_metrics) ) +or ( binary_id(=apollo-router::integration_tests) & test(=normal_query_with_defer_accept_header) ) +or ( binary_id(=apollo-router::integration_tests) & test(=persisted_queries) ) +or ( binary_id(=apollo-router::integration_tests) & test(=queries_should_work_over_get) ) +or ( binary_id(=apollo-router::integration_tests) & test(=queries_should_work_over_post) ) +or ( binary_id(=apollo-router::integration_tests) & test(=queries_should_work_with_compression) ) +or ( binary_id(=apollo-router::integration_tests) & test(=query_just_under_recursion_limit) ) +or ( binary_id(=apollo-router::integration_tests) & test(=query_just_under_token_limit) ) +or ( binary_id(=apollo-router::samples) & test(=/basic/query1) ) +or ( binary_id(=apollo-router::samples) & test(=/basic/query2) ) or ( binary_id(=apollo-router::samples) & test(=/enterprise/entity-cache/invalidation) ) or ( binary_id(=apollo-router::samples) & test(=/enterprise/entity-cache/invalidation-subgraph) ) or ( binary_id(=apollo-router::samples) & test(=/enterprise/entity-cache/invalidation-subgraph-type) ) @@ -85,6 +139,10 @@ or ( binary_id(=apollo-router::set_context) & test(=test_set_context_no_typename or ( binary_id(=apollo-router::set_context) & test(=test_set_context_type_mismatch) ) or ( binary_id(=apollo-router::set_context) & test(=test_set_context_union) ) or ( binary_id(=apollo-router::set_context) & test(=test_set_context_unrelated_fetch_failure) ) +or ( binary_id(=apollo-router::set_context) & test(=test_set_context_with_null) ) +or ( binary_id(=apollo-router::type_conditions) & test(=test_type_conditions_disabled) ) +or ( binary_id(=apollo-router::type_conditions) & test(=test_type_conditions_enabled) ) +or ( binary_id(=apollo-router::type_conditions) & test(=test_type_conditions_enabled_generate_query_fragments) ) ''' [profile.ci] diff --git a/CHANGELOG.md b/CHANGELOG.md index de369468ce..c2db241d92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,218 @@ All notable changes to Router will be documented in this file. This project adheres to [Semantic Versioning v2.0.0](https://semver.org/spec/v2.0.0.html). +# [1.52.0] - 2024-07-30 + +## 🚀 Features + +### Provide helm support for when router's health_check's default path is not being used([Issue #5652](https://github.com/apollographql/router/issues/5652)) + +When helm chart is defining the liveness and readiness check probes, if the router has been configured to use a non-default health_check path, use that rather than the default ( /health ) + +By [Jon Christiansen](https://github.com/theJC) in https://github.com/apollographql/router/pull/5653 + +### Support new span and metrics formats for entity caching ([PR #5625](https://github.com/apollographql/router/pull/5625)) + +Metrics of the router's entity cache have been converted to the latest format with support for custom telemetry. + +The following example configuration shows the the `cache` instrument, the `cache` selector in the subgraph service, and the `cache` attribute of a subgraph span: + +```yaml +telemetry: + instrumentation: + instruments: + default_requirement_level: none + cache: + apollo.router.operations.entity.cache: + attributes: + entity.type: true + subgraph.name: + subgraph_name: true + supergraph.operation.name: + supergraph_operation_name: string + subgraph: + only_cache_hit_on_subgraph_products: + type: counter + value: + cache: hit + unit: hit + description: counter of subgraph request cache hit on subgraph products + condition: + all: + - eq: + - subgraph_name: true + - products + - gt: + - cache: hit + - 0 + attributes: + subgraph.name: true + supergraph.operation.name: + supergraph_operation_name: string + +``` + +To learn more, go to [Entity caching docs](https://www.apollographql.com/docs/router/configuration/entity-caching). + +By [@Geal](https://github.com/Geal) and [@bnjjj](https://github.com/bnjjj) in https://github.com/apollographql/router/pull/5625 + +### Helm: Support renaming key for retrieving APOLLO_KEY secret ([Issue #5661](https://github.com/apollographql/router/issues/5661)) + +A user of the router Helm chart can now rename the key used to retrieve the value of the secret key referenced by `APOLLO_KEY`. + +Previously, the router Helm chart hardcoded the key name to `managedFederationApiKey`. This didn't support users whose infrastructure required custom key names when getting secrets, such as Kubernetes users who need to use specific key names to access a `secretStore` or `externalSecret`. This change provides a user the ability to control the name of the key to use in retrieving that value. + +By [Jon Christiansen](https://github.com/theJC) in https://github.com/apollographql/router/pull/5662 + +## 🐛 Fixes + +### Prevent Datadog timeout errors in logs ([Issue #2058](https://github.com/apollographql/router/issue/2058)) + +The router's Datadog exporter has been updated to reduce the frequency of logged errors related to connection pools. + +Previously, the connection pools used by the Datadog exporter frequently timed out, and each timeout logged an error like the following: + +``` +2024-07-19T15:28:22.970360Z ERROR OpenTelemetry trace error occurred: error sending request for url (http://127.0.0.1:8126/v0.5/traces): connection error: Connection reset by peer (os error 54) +``` + +Now, the pool timeout for the Datadog exporter has been changed so that timeout errors happen much less frequently. + +By [@BrynCooke](https://github.com/BrynCooke) in https://github.com/apollographql/router/pull/5692 + +### Allow service version overrides ([PR #5689](https://github.com/apollographql/router/pull/5689)) + +The router now supports configuration of `service.version` via YAML file configuration. This enables users to produce custom versioned builds of the router. + + +The following example overrides the version to be `1.0`: +```yaml +telemetry: + exporters: + tracing: + common: + resource: + service.version: 1.0 +``` + + +By [@BrynCooke](https://github.com/BrynCooke) in https://github.com/apollographql/router/pull/5689 + +### Populate Datadog `span.kind` ([PR #5609](https://github.com/apollographql/router/pull/5609)) + +Because Datadog traces use `span.kind` to differentiate between different types of spans, the router now ensures that `span.kind` is correctly populated using the OpenTelemetry span kind, which has a 1-2-1 mapping to those set out in [dd-trace](https://github.com/DataDog/dd-trace-go/blob/main/ddtrace/ext/span_kind.go). + +By [@BrynCooke](https://github.com/BrynCooke) in https://github.com/apollographql/router/pull/5609 + +### Remove unnecessary internal metric events from traces and spans ([PR #5649](https://github.com/apollographql/router/pull/5649)) + +The router no longer includes some internal metric events in traces and spans that shouldn't have been included originally. + +By [@bnjjj](https://github.com/bnjjj) in https://github.com/apollographql/router/pull/5649 + +### Support Datadog span metrics ([PR #5609](https://github.com/apollographql/router/pull/5609)) + +When using the APM view in Datadog, the router now displays span metrics for top-level spans or spans with the `_dd.measured` flag set. + +The router sets the `_dd.measured` flag by default for the following spans: + +* `request` +* `router` +* `supergraph` +* `subgraph` +* `subgraph_request` +* `http_request` +* `query_planning` +* `execution` +* `query_parsing` + +To enable or disable span metrics for any span, configure `span_metrics` for the Datadog exporter: + +```yaml +telemetry: + exporters: + tracing: + datadog: + enabled: true + span_metrics: + # Disable span metrics for supergraph + supergraph: false + # Enable span metrics for my_custom_span + my_custom_span: true +``` + +By [@BrynCooke](https://github.com/BrynCooke) in https://github.com/apollographql/router/pull/5609 and https://github.com/apollographql/router/pull/5703 + +### Use spawn_blocking for query parsing and validation ([PR #5235](https://github.com/apollographql/router/pull/5235)) + +To prevent its executor threads from blocking on large queries, the router now runs query parsing and validation in a Tokio blocking task. + +By [@xuorig](https://github.com/xuorig) in https://github.com/apollographql/router/pull/5235 + +## 🛠 Maintenance + +### chore: Update rhai to latest release (1.19.0) ([PR #5655](https://github.com/apollographql/router/pull/5655)) + +In Rhai 1.18.0, there were changes to how exceptions within functions were created. For details see: https://github.com/rhaiscript/rhai/blob/7e0ac9d3f4da9c892ed35a211f67553a0b451218/CHANGELOG.md?plain=1#L12 + +We've modified how we handle errors raised by Rhai to comply with this change, which means error message output is affected. The change means that errors in functions will no longer document which function the error occurred in, for example: + +```diff +- "rhai execution error: 'Runtime error: I have raised an error (line 223, position 5)\nin call to function 'process_subgraph_response_string''" ++ "rhai execution error: 'Runtime error: I have raised an error (line 223, position 5)'" +``` + +Making this change allows us to keep up with the latest version (1.19.0) of Rhai. + +By [@garypen](https://github.com/garypen) in https://github.com/apollographql/router/pull/5655 + +### Add version in the entity cache hash ([PR #5701](https://github.com/apollographql/router/pull/5701)) + +The hashing algorithm of the router's entity cache has been updated to include the entity cache version. + +[!IMPORTANT] +If you have previously enabled [entity caching](https://www.apollographql.com/docs/router/configuration/entity-caching), you should expect additional cache regeneration costs when updating to this version of the router while the new hashing algorithm comes into service. + +By [@bnjjj](https://github.com/bnjjj) in https://github.com/apollographql/router/pull/5701 + +### Improve testing by avoiding cache effects and redacting tracing details ([PR #5638](https://github.com/apollographql/router/pull/5638)) + +We've had some problems with flaky tests and this PR addresses some of them. + +The router executes in parallel and concurrently. Many of our tests use snapshots to try and make assertions that functionality is continuing to work correctly. Unfortunately, concurrent/parallel execution and static snapshots don't co-operate very well. Results may appear in pseudo-random order (compared to snapshot expectations) and so tests become flaky and fail without obvious cause. + +The problem becomes particularly acute with features which are specifically designed for highly concurrent operation, such as batching. + +This set of changes addresses some of the router testing problems by: + +1. Making items in a batch test different enough that caching effects are avoided. +2. Redacting various details so that sequencing is not as much of an issue in the otel traces tests. + +By [@garypen](https://github.com/garypen) in https://github.com/apollographql/router/pull/5638 + +## 📚 Documentation + +### Update router naming conventions ([PR #5400](https://github.com/apollographql/router/pull/5400)) + +Renames our router product to distinguish between our non-commercial and commercial offerings. Instead of referring to the **Apollo Router**, we now refer to the following: +- **Apollo Router Core** is Apollo’s free-and-open (ELv2 licensed) implementation of a routing runtime for supergraphs. +- **GraphOS Router** is based on the Apollo Router Core and fully integrated with GraphOS. GraphOS Routers provide access to GraphOS’s commercial runtime features. + + +By [@shorgi](https://github.com/shorgi) in https://github.com/apollographql/router/pull/5400 + +## 🧪 Experimental + +### Enable Rust-based API schema implementation ([PR #5623](https://github.com/apollographql/router/pull/5623)) + +The router has transitioned to solely using a Rust-based API schema generation implementation. + +Previously, the router used a Javascript-based implementation. After testing for a few months, we've validated the improved performance and robustness of the new Rust-based implementation, so the router now only uses it. + +By [@goto-bus-stop](https://github.com/goto-bus-stop) in https://github.com/apollographql/router/pull/5623 + + + # [1.51.0] - 2024-07-16 ## 🚀 Features diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 334d1afe0e..31ee69219e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,10 @@ -# Contributing to Apollo Router +# Contributing to Apollo Router Core -## Before you contribute! +## Before you contribute -> The Apollo Router is a project by [Apollo GraphQL] and is not currently ready for +> The Apollo Router Core is a project by [Apollo GraphQL] and is not currently ready for > external feature contributors, though some documentation contributions may be > accepted. We will try to publish a roadmap as soon as possible. @@ -14,10 +14,10 @@ That will allow us to figure out a way to solve the issue together, and possibly ## Setting up the project -The Apollo Router is written in [Rust]. In order to contribute, you'll need to have Rust installed. To install Rust, +The Apollo Router Core is written in [Rust]. In order to contribute, you'll need to have Rust installed. To install Rust, visit [https://www.rust-lang.org/tools/install]. -Rust has a build tool and package manager called [`cargo`] that you'll use to interact with the Apollo Router's code. +Rust has a build tool and package manager called [`cargo`] that you'll use to interact with the router's code. To build the CLI: @@ -29,7 +29,7 @@ To run the CLI: ```bash cargo run -- -# e.g. 'cargo run -- --help' will run the Apollo Router's help command +# e.g. 'cargo run -- --help' will run the router's help command ``` Refer to [the README file](README.md) or run `cargo run --help` for more information. @@ -41,7 +41,7 @@ Refer to [the README file](README.md) or run `cargo run --help` for more informa ## Project Structure -- `crates/apollo-router`: the web `Apollo Router` sources. This includes everything required to expose Apollo Router's functionality as a web server, such as serialization / deserialization, configuration management, web server set up, logging configuration etc. As well as everything required to handle graphql queries: +- `crates/apollo-router`: the web `Apollo Router` sources. This includes everything required to expose Apollo Router Core's functionality as a web server, such as serialization / deserialization, configuration management, web server set up, logging configuration etc. As well as everything required to handle graphql queries: - query plan building - query plan execution @@ -55,15 +55,15 @@ Some of the functionalities rely on the current Javascript / TypeScript implemen ## Documentation -Documentation for using and contributing to the Apollo Router is built using Gatsby +Documentation for using and contributing to the Apollo Router Core is built using Gatsby and [Apollo's Docs Theme for Gatsby](https://github.com/apollographql/gatsby-theme-apollo/tree/master/packages/gatsby-theme-apollo-docs) . To contribute to these docs, you can add or edit the markdown & MDX files in the `docs/source` directory. -To build and run the documentation site locally, you'll also need a clone of +To build and run the documentation site locally, you'll also need a clone of the [apollographql/docs](https://github.com/apollographql/docs/) repository -and run `npm run start:router` from there, after following +and run `npm run start:router` from there, after following [installation instructions](https://github.com/apollographql/docs/#developing-locally). This will start up a development server with live reload enabled. You can see the docs by @@ -87,7 +87,7 @@ XTASKs: - **Tests**: The CI will run `cargo xtask test` which will test each relevant permutation of the available features and run the demo subgraphs. - **Lints**: The CI will check for lints and clippy compliance. -- **Checks**: The CI will run cargo-deny to make sure the Apollo Router doesn't suffer an existing CVE, and that each dependency used by the Apollo Router is compatible with our license. +- **Checks**: The CI will run cargo-deny to make sure the router doesn't suffer an existing CVE, and that each dependency used by the router is compatible with our license. After you have opened your PR and all of the status checks are passing, please assign it to one of the maintainers (found in the bottom of [the README](./README.md#contributing) who will review it and give feedback. diff --git a/Cargo.lock b/Cargo.lock index f6964d44da..604247d2a0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -424,7 +424,7 @@ dependencies = [ [[package]] name = "apollo-federation" -version = "1.51.0" +version = "1.52.0" dependencies = [ "apollo-compiler", "derive_more", @@ -471,7 +471,7 @@ dependencies = [ [[package]] name = "apollo-router" -version = "1.51.0" +version = "1.52.0" dependencies = [ "access-json", "ahash", @@ -639,7 +639,7 @@ dependencies = [ [[package]] name = "apollo-router-benchmarks" -version = "1.51.0" +version = "1.52.0" dependencies = [ "apollo-parser", "apollo-router", @@ -655,7 +655,7 @@ dependencies = [ [[package]] name = "apollo-router-scaffold" -version = "1.51.0" +version = "1.52.0" dependencies = [ "anyhow", "cargo-scaffold", diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 2e2a013996..c46019ff93 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,26 +1,26 @@ # Development -The **Apollo Router** is a configurable, high-performance **graph router** for a [federated graph](https://www.apollographql.com/docs/federation/): +The **Apollo Router Core** is a configurable, high-performance **graph router** for a [federated graph](https://www.apollographql.com/docs/federation/): ## Crates - * `configuration` - Config model and loading. - * `query planner` - Query plan model and a caching wrapper for calling out to the nodejs query planner. - * `execution` - Converts a query plan to a stream. - * `server` - Handles requests, +* `configuration` - Config model and loading. +* `query planner` - Query plan model and a caching wrapper for calling out to the nodejs query planner. +* `execution` - Converts a query plan to a stream. +* `server` - Handles requests, obtains a query plan from the query planner, obtains an execution pipeline, returns the results ## Binaries - * `router` - Starts a server. +* `router` - Starts a server. ## Development -You will need a recent version of rust (`1.72` works well as of writing). +You will need a recent version of rust (`1.72` works well as of writing). Installing rust [using rustup](https://www.rust-lang.org/tools/install) is -the recommended way to do it as it will install rustup, rustfmt and other +the recommended way to do it as it will install rustup, rustfmt and other goodies that are not always included by default in other rust distribution channels: ``` @@ -39,9 +39,9 @@ git config --local core.hooksPath .githooks/ Use `cargo build --all-targets` to build the project. -Some tests use external services such as Jaeger and Redis. +Some tests use external services such as Jaeger and Redis. -To start these services: +To start these services: ``` docker-compose up -d @@ -51,16 +51,16 @@ docker-compose up -d have issues and you want to see the logs or if you want to run the service in foreground. -### Run Apollo Router against the docker-compose or Node.js setup +### Run against the docker-compose or Node.js setup -Once the subgraphs are up and running, run Apollo Router with this command: +Once the subgraphs are up and running, run the router with this command: ```shell cargo run --release -- -s ./examples/graphql/local.graphql -c examples/telemetry/jaeger.router.yaml ``` -Go to https://studio.apollographql.com/sandbox/explorer to make queries and -http://localhost:16686/ to reach Jaeger. +Go to to make queries and + to reach Jaeger. ### Strict linting and license compliance @@ -73,11 +73,13 @@ and check for license compliance. Use `cargo xtask all` to run all of the checks the CI will run. The CI checks require `cargo-deny` and `cargo-about` which can both be installed by running: -- `cargo install cargo-deny` -- `cargo install cargo-about` + +* `cargo install cargo-deny` +* `cargo install cargo-about` Updating the snapshots used during testing requires installing `cargo-insta`: -- `cargo install cargo-insta` + +* `cargo install cargo-insta` They also need you to have the federation-demo project up and running, as explained in the Getting started section above. @@ -86,7 +88,6 @@ as explained in the Getting started section above. If you are adding a new feature or modifying an existing feature then consult the [yaml design guidance](dev-docs/yaml-design-guidance.md) page. - ### Investigating memory usage There are two features: `dhat-heap` and `dhat-ad-hoc` which may be enabled for investigating memory issues @@ -95,11 +96,13 @@ with the router. You may enable either or both, depending on the kind of problem You have to build the router with your choice of feature flags and you must use the `release-dhat` profile. e.g.: heap and ad-hoc allocation tracing + ```shell # e.g. heap and ad-hoc allocation tracing: cargo build --profile release-dhat --features dhat-heap,dhat-ad-hoc ``` e.g.: heap allocation tracing + ```shell cargo build --profile release-dhat --features dhat-heap ``` @@ -113,7 +116,7 @@ For more details on interpreting these files and running tests, see the [dhat-rs ### Troubleshoot -+ If you have an issue with rust-analyzer reporting an unresolved import about `derivative::Derivative` [check this solution](https://github.com/rust-analyzer/rust-analyzer/issues/7459#issuecomment-876796459) found in a rust-analyzer issue. +* If you have an issue with rust-analyzer reporting an unresolved import about `derivative::Derivative` [check this solution](https://github.com/rust-analyzer/rust-analyzer/issues/7459#issuecomment-876796459) found in a rust-analyzer issue. ## Project maintainers diff --git a/README.md b/README.md index e865d321d0..0f87d6d343 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,11 @@ Join 1000+ engineers at GraphQL Summit for talks, workshops, and office hours, O --- -# Apollo Router +# Apollo Router Core -The **Apollo Router** is a configurable, high-performance **graph router** written in Rust to run a [federated supergraph](https://www.apollographql.com/docs/federation/) that uses [Apollo Federation 2](https://www.apollographql.com/docs/federation/v2/federation-2/new-in-federation-2). +The **Apollo Router Core** is a configurable, high-performance **graph router** written in Rust to run a [federated supergraph](https://www.apollographql.com/docs/federation/) that uses [Apollo Federation 2](https://www.apollographql.com/docs/federation/v2/federation-2/new-in-federation-2). -Apollo Router is well-tested, regularly benchmarked, includes most major features of Apollo Gateway and is able to serve production-scale workloads. Please note that the (pre-1.0) version is not yet "semver stable" and we may still make breaking changes. Generally speaking, we expect most breaking changes to be on the plugin API and the configuration file format. We will clearly convey such changes in the release notes. +Apollo Router Core is well-tested, regularly benchmarked, includes most major features of Apollo Gateway and is able to serve production-scale workloads. New releases and their release notes (along with notes about any breaking changes) can be found on the [Releases](https://github.com/apollographql/router/releases) page, and the latest release can always be found [on the latest page](https://github.com/apollographql/router/releases/latest). The `CHANGELOG.md` at the root of this repository also contains _unreleased_ changes in addition to the full history of changes. @@ -21,13 +21,13 @@ Currently, we're publishing new releases every 1-2 weeks. ## Getting started -Follow the [quickstart tutorial](https://www.apollographql.com/docs/router/quickstart/) to get up and running with the Apollo Router. +Follow the [quickstart tutorial](https://www.apollographql.com/docs/router/quickstart/) to get up and running with the router. See [the documentation](https://www.apollographql.com/docs/router) for more details. ## Usage -Apollo Router requires [a supergraph file](https://www.apollographql.com/docs/rover/commands/supergraphs/) to be passed as the `--supergraph` argument and [an optional configuration file](https://www.apollographql.com/docs/router/configuration/overview/#yaml-config-file). +Apollo Router Core requires [a supergraph file](https://www.apollographql.com/docs/rover/commands/supergraphs/) to be passed as the `--supergraph` argument and [an optional configuration file](https://www.apollographql.com/docs/router/configuration/overview/#yaml-config-file). to be supplied. These are either located in the current directory or explicitly specified via flag, either by an absolute path, or a path relative to the current directory. @@ -81,7 +81,7 @@ Check out the [Odyssey](https://odyssey.apollographql.com/) learning platform, t ## Design principles -The development of the Apollo Router is driven by the following design principles that inform +The development of the Apollo Router Core is driven by the following design principles that inform architecture decisions and implementation. **Correctness:** the router strives to be the most correct implementation of GraphQL and Federation, we care about testing and documenting everything implied by the specification, up to failure cases. The router’s behavior should follow the principle of least surprise for developers. @@ -91,6 +91,7 @@ architecture decisions and implementation. **Safe experimentation:** the router will support all the future work around Federation, so it must allow new ideas and explorations without disturbing existing features. The project is still in movement, we cannot allow it to crystallize too early, while still following the principles of correctness and reliability. **Usability:** the router must be simple to operate. Prefer extensibility over configuration options, and ensure that the user has enough information to help themselves when things go wrong. For example: + * Common environmental misconfiguration should be detected and surfaced to the user in the form of mitigation steps. * User supplied extensions should be observable and flagged when they cause performance issues. Tell the users how much time an extension is consuming per request and why. diff --git a/apollo-federation/Cargo.toml b/apollo-federation/Cargo.toml index 4a5aa3a1aa..a43735f123 100644 --- a/apollo-federation/Cargo.toml +++ b/apollo-federation/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "apollo-federation" -version = "1.51.0" +version = "1.52.0" authors = ["The Apollo GraphQL Contributors"] edition = "2021" description = "Apollo Federation" diff --git a/apollo-router-benchmarks/Cargo.toml b/apollo-router-benchmarks/Cargo.toml index c2acf8a5c8..cc1e73902a 100644 --- a/apollo-router-benchmarks/Cargo.toml +++ b/apollo-router-benchmarks/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "apollo-router-benchmarks" -version = "1.51.0" +version = "1.52.0" authors = ["Apollo Graph, Inc. "] edition = "2021" license = "Elastic-2.0" diff --git a/apollo-router-scaffold/Cargo.toml b/apollo-router-scaffold/Cargo.toml index aa62f1b73d..7bd39a628b 100644 --- a/apollo-router-scaffold/Cargo.toml +++ b/apollo-router-scaffold/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "apollo-router-scaffold" -version = "1.51.0" +version = "1.52.0" authors = ["Apollo Graph, Inc. "] edition = "2021" license = "Elastic-2.0" diff --git a/apollo-router-scaffold/templates/base/Cargo.template.toml b/apollo-router-scaffold/templates/base/Cargo.template.toml index 4733b6c87d..21f679e602 100644 --- a/apollo-router-scaffold/templates/base/Cargo.template.toml +++ b/apollo-router-scaffold/templates/base/Cargo.template.toml @@ -22,7 +22,7 @@ apollo-router = { path ="{{integration_test}}apollo-router" } apollo-router = { git="https://github.com/apollographql/router.git", branch="{{branch}}" } {{else}} # Note if you update these dependencies then also update xtask/Cargo.toml -apollo-router = "1.51.0" +apollo-router = "1.52.0" {{/if}} {{/if}} async-trait = "0.1.52" diff --git a/apollo-router-scaffold/templates/base/xtask/Cargo.template.toml b/apollo-router-scaffold/templates/base/xtask/Cargo.template.toml index d5c86be60b..5194c11c10 100644 --- a/apollo-router-scaffold/templates/base/xtask/Cargo.template.toml +++ b/apollo-router-scaffold/templates/base/xtask/Cargo.template.toml @@ -13,7 +13,7 @@ apollo-router-scaffold = { path ="{{integration_test}}apollo-router-scaffold" } {{#if branch}} apollo-router-scaffold = { git="https://github.com/apollographql/router.git", branch="{{branch}}" } {{else}} -apollo-router-scaffold = { git = "https://github.com/apollographql/router.git", tag = "v1.51.0" } +apollo-router-scaffold = { git = "https://github.com/apollographql/router.git", tag = "v1.52.0" } {{/if}} {{/if}} anyhow = "1.0.58" diff --git a/apollo-router/Cargo.toml b/apollo-router/Cargo.toml index ba4daf69c9..26618a16a6 100644 --- a/apollo-router/Cargo.toml +++ b/apollo-router/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "apollo-router" -version = "1.51.0" +version = "1.52.0" authors = ["Apollo Graph, Inc. "] repository = "https://github.com/apollographql/router/" documentation = "https://docs.rs/apollo-router" @@ -68,7 +68,7 @@ askama = "0.12.1" access-json = "0.1.0" anyhow = "1.0.86" apollo-compiler.workspace = true -apollo-federation = { path = "../apollo-federation", version = "=1.51.0" } +apollo-federation = { path = "../apollo-federation", version = "=1.52.0" } arc-swap = "1.6.0" async-channel = "1.9.0" async-compression = { version = "0.4.6", features = [ diff --git a/apollo-router/README.md b/apollo-router/README.md index 4934b8a099..e591f2b386 100644 --- a/apollo-router/README.md +++ b/apollo-router/README.md @@ -1,11 +1,11 @@ [![Version](https://img.shields.io/crates/v/apollo-router.svg)](https://crates.io/crates/apollo-router) [![Docs.rs](https://docs.rs/apollo-router/badge.svg)](https://docs.rs/apollo-router) -# Apollo Router +# Apollo Router Core [Apollo Router](https://www.apollographql.com/docs/router/) -The **Apollo Router** is a configurable, high-performance **graph router** written in Rust to run a [federated supergraph](https://www.apollographql.com/docs/federation/) that uses [Apollo Federation 2](https://www.apollographql.com/docs/federation/v2/federation-2/new-in-federation-2). It is well-tested, regularly benchmarked, includes major features of Apollo Gateway and serves production-scale workloads. +The **Apollo Router Core** is a configurable, high-performance **graph router** written in Rust to run a [federated supergraph](https://www.apollographql.com/docs/federation/) that uses [Apollo Federation 2](https://www.apollographql.com/docs/federation/v2/federation-2/new-in-federation-2). It is well-tested, regularly benchmarked, includes major features of Apollo Gateway and serves production-scale workloads. The latest release can always be found at the top of [the Releases page](https://github.com/apollographql/router/releases/) along with past releases and release notes. We follow the [Semantic Versioning 2.0.0](https://semver.org/) specification when publishing new versions. A [`CHANGELOG.md` is also included](https://github.com/apollographql/router/blob/main/CHANGELOG.md) in the Git repository with information about each release. @@ -20,9 +20,9 @@ See [the documentation](https://www.apollographql.com/docs/router) for more deta - including additional customizations - from source, and more! -## Using the Apollo Router as a library +## Using the Apollo Router Core as a library -Most Apollo Router features can be defined using our [YAML configuration](https://www.apollographql.com/docs/router/configuration/overview) and many customizations can be written with [Rhai scripts](https://www.apollographql.com/docs/router/customizations/rhai) which work on published binaries of the Router and do not require compilation. +Most Apollo Router Core features can be defined using our [YAML configuration](https://www.apollographql.com/docs/router/configuration/overview) and many customizations can be written with [Rhai scripts](https://www.apollographql.com/docs/router/customizations/rhai) which work on published binaries of the router and do not require compilation. If you prefer to write customizations in Rust or need more advanced customizations, see our section on [native customizations](https://www.apollographql.com/docs/router/customizations/native) for information on how to use `apollo-router` as a Rust library. We also publish Rust-specific documentation on our [`apollo-router` crate docs](https://docs.rs/crate/apollo-router). diff --git a/dockerfiles/tracing/docker-compose.datadog.yml b/dockerfiles/tracing/docker-compose.datadog.yml index d353c22089..68cb7cdbbd 100644 --- a/dockerfiles/tracing/docker-compose.datadog.yml +++ b/dockerfiles/tracing/docker-compose.datadog.yml @@ -3,7 +3,7 @@ services: apollo-router: container_name: apollo-router - image: ghcr.io/apollographql/router:v1.51.0 + image: ghcr.io/apollographql/router:v1.52.0 volumes: - ./supergraph.graphql:/etc/config/supergraph.graphql - ./router/datadog.router.yaml:/etc/config/configuration.yaml diff --git a/dockerfiles/tracing/docker-compose.jaeger.yml b/dockerfiles/tracing/docker-compose.jaeger.yml index 56d42a866f..254b9e98f8 100644 --- a/dockerfiles/tracing/docker-compose.jaeger.yml +++ b/dockerfiles/tracing/docker-compose.jaeger.yml @@ -4,7 +4,7 @@ services: apollo-router: container_name: apollo-router #build: ./router - image: ghcr.io/apollographql/router:v1.51.0 + image: ghcr.io/apollographql/router:v1.52.0 volumes: - ./supergraph.graphql:/etc/config/supergraph.graphql - ./router/jaeger.router.yaml:/etc/config/configuration.yaml diff --git a/dockerfiles/tracing/docker-compose.zipkin.yml b/dockerfiles/tracing/docker-compose.zipkin.yml index 5b26c558d0..b94e872653 100644 --- a/dockerfiles/tracing/docker-compose.zipkin.yml +++ b/dockerfiles/tracing/docker-compose.zipkin.yml @@ -4,7 +4,7 @@ services: apollo-router: container_name: apollo-router build: ./router - image: ghcr.io/apollographql/router:v1.51.0 + image: ghcr.io/apollographql/router:v1.52.0 volumes: - ./supergraph.graphql:/etc/config/supergraph.graphql - ./router/zipkin.router.yaml:/etc/config/configuration.yaml diff --git a/docs/shared/elastic-notice.mdx b/docs/shared/elastic-notice.mdx index 057bbd91c0..f0bb6e279f 100644 --- a/docs/shared/elastic-notice.mdx +++ b/docs/shared/elastic-notice.mdx @@ -1,5 +1,5 @@ -The Apollo Router source code and all its distributions are made available under the [Elastic License v2.0 (ELv2) license](https://www.apollographql.com/docs/resources/elastic-license-v2-faq/#can-i-extend-or-modify-the-gateway-or-router-by-creating-plugins). +The Apollo Router Core source code and all its distributions are made available under the [Elastic License v2.0 (ELv2) license](https://www.apollographql.com/docs/resources/elastic-license-v2-faq/#can-i-extend-or-modify-the-gateway-or-router-by-creating-plugins). diff --git a/docs/shared/native-plugin-notice.mdx b/docs/shared/native-plugin-notice.mdx index 96e52bf7e7..7d957b0d31 100644 --- a/docs/shared/native-plugin-notice.mdx +++ b/docs/shared/native-plugin-notice.mdx @@ -1,4 +1,4 @@ -⚠️ **Apollo doesn't recommend creating native plugins for the Apollo Router**, for the following reasons: +⚠️ Apollo doesn't recommend creating native plugins for the Apollo Router Core or GraphOS Router, for the following reasons: - Native plugins require familiarity with programming in Rust. - Native plugins require compiling a custom router binary from source, which can introduce unexpected behavior in your router that's difficult to diagnose and support. diff --git a/docs/shared/register-federated-cli.mdx b/docs/shared/register-federated-cli.mdx index a8ad0cdb93..e2b1738bbf 100644 --- a/docs/shared/register-federated-cli.mdx +++ b/docs/shared/register-federated-cli.mdx @@ -3,7 +3,7 @@ In a federated architecture, each of your graph's [subgraphs](https://www.apollo ```mermaid graph LR; subgraph " " - gateway([Apollo Router]); + gateway([GraphOS Router]); subgraphA[Products subgraph]; subgraphB[Reviews subgraph]; subgraphC[Inventory subgraph]; @@ -36,6 +36,6 @@ Then, **do the following for each of your subgraphs**: rover subgraph introspect http://localhost:4000 | rover subgraph publish my-graph@my-variant --name products --routing-url http://products-graphql.svc.cluster.local:4001/ --schema - ``` -As you register your subgraph schemas, the schema registry attempts to **compose** their latest versions into a single **supergraph schema**. Whenever composition succeeds, the Apollo Router can fetch the latest supergraph schema from the registry. +As you register your subgraph schemas, the schema registry attempts to **compose** their latest versions into a single **supergraph schema**. Whenever composition succeeds, the GraphOS Router can fetch the latest supergraph schema from the registry. You can also manually fetch your latest supergraph schema with the `rover supergraph fetch` command, or retrieve it from your graph's **Schema > SDL** tab in GraphOS Studio. diff --git a/docs/shared/router-lifecycle-services.mdx b/docs/shared/router-lifecycle-services.mdx index be4fe5cb2d..12b57bc588 100644 --- a/docs/shared/router-lifecycle-services.mdx +++ b/docs/shared/router-lifecycle-services.mdx @@ -1,4 +1,4 @@ -The Apollo Router's request lifecycle has three major services: +A router's request lifecycle has three major services: * **Router service** - Handles an incoming request before it is parsed. Works within a context of opaque bytes. * **Supergraph service** - Handles a request after it has been parsed and before it is sent to the subgraph. Works within a GraphQL context. diff --git a/docs/source/configuration/authn-jwt.mdx b/docs/source/configuration/authn-jwt.mdx index 2d1bc6061c..696fa394d2 100644 --- a/docs/source/configuration/authn-jwt.mdx +++ b/docs/source/configuration/authn-jwt.mdx @@ -1,12 +1,12 @@ --- -title: JWT Authentication in the Apollo Router +title: JWT Authentication in the GraphOS Router subtitle: Restrict access to credentialed users and systems -description: Protect sensitive data by enabling JWT authentication in the Apollo Router. Restrict access to credentialed users and systems. +description: Protect sensitive data by enabling JWT authentication in the Apollo GraphOS Router. Restrict access to credentialed users and systems. --- -Authentication is crucial to prevent illegitimate access and protect sensitive data in your graph. The Apollo Router supports request authentication and key rotation via the [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519) (**JWT**) and [JSON Web Key](https://www.rfc-editor.org/rfc/rfc7517) (**JWK**) standards. This support is compatible with popular identity providers (**IdPs**) like Okta and Auth0. +Authentication is crucial to prevent illegitimate access and protect sensitive data in your graph. The GraphOS Router supports request authentication and key rotation via the [JSON Web Token](https://www.rfc-editor.org/rfc/rfc7519) (**JWT**) and [JSON Web Key](https://www.rfc-editor.org/rfc/rfc7517) (**JWK**) standards. This support is compatible with popular identity providers (**IdPs**) like Okta and Auth0. By enabling JWT authentication, you can block malicious traffic at the _edge_ of your graph instead of relying on [header forwarding](./header-propagation/) to propagate tokens to your subgraphs. @@ -18,7 +18,7 @@ Your subgraphs should always be accessible _only_ via the router—not directly ## How JWT authentication works -These are the high-level steps of JWT-based authentication with the Apollo Router: +These are the high-level steps of JWT-based authentication with the GraphOS Router: 1. Whenever a client authenticates with your system, your IdP issues that client a valid JSON Web Token (JWT). 2. In its subsequent requests to your router, the authenticated client provides its JWT in a designated HTTP header. @@ -201,7 +201,7 @@ The default value is `false`. ## Working with JWT claims -After the Apollo Router validates a client request's JWT, it adds that token's **claims** to the request's context at this key: `apollo_authentication::JWT::claims` +After the GraphOS Router validates a client request's JWT, it adds that token's **claims** to the request's context at this key: `apollo_authentication::JWT::claims` > - If no JWT is present for a client request, this context value is the empty tuple, `()`. > - If a JWT _is_ present but validation of the JWT fails, the router _rejects_ the request. @@ -215,7 +215,7 @@ authorization: **Claims** are the individual details of a JWT's scope. They might include details like the ID of the associated user, any roles assigned to that user, and the JWT's expiration time. [See the spec.](https://www.rfc-editor.org/rfc/rfc7519#section-4) -Because claims are added to the context, you can define custom logic for handling each request based on the details of its claims. You can define this logic within a Rhai script or external coprocessor at the supergraph service level (for more on these options, see [Customizations for the Apollo Router](../customizations/overview/)). +Because claims are added to the context, you can define custom logic for handling each request based on the details of its claims. You can define this logic within a Rhai script or external coprocessor at the supergraph service level (for more on these options, see [Router Customizations](../customizations/overview/)). Below are 2 example [Rhai script](../customizations/rhai/) customizations that demonstrate actions the router can perform based on a request's claims. @@ -420,11 +420,11 @@ For more information, refer to [the coprocessor documentation](../customizations - **Most third-party IdP services create and host a JSON Web Key Set (JWKS) for you.** Read this section only if you use a _custom_ IdP that doesn't publish its JWKS at a router-accessible URL. -- To be compatible with JWT authentication supported by Apollo Router, your IdP (or whatever service issues JWTs to authenticated clients) must use one of the [signature algorithms](https://crates.io/crates/jsonwebtoken#algorithms) supported by the router. +- To be compatible with JWT authentication supported by GraphOS Router, your IdP (or whatever service issues JWTs to authenticated clients) must use one of the [signature algorithms](https://crates.io/crates/jsonwebtoken#algorithms) supported by the router. -The Apollo Router obtains each JSON Web Key (JWK) that it uses from the URLs that you specify via the [`jwks`](#jwks) configuration option. Each URL must provide a set of valid JWKs in a single JSON object called a JWK Set (or **JWKS**). +The GraphOS Router obtains each JSON Web Key (JWK) that it uses from the URLs that you specify via the [`jwks`](#jwks) configuration option. Each URL must provide a set of valid JWKs in a single JSON object called a JWK Set (or **JWKS**). Consult your IdP's documentation to obtain the [JWKS URL](#jwks) to pass to your router. @@ -737,9 +737,9 @@ This matching strategy is necessary because some identity providers (IdPs) don't ## Forwarding JWTs to subgraphs -Because the Apollo Router handles validating incoming JWTs, you rarely need to pass those JWTs to individual subgraphs in their entirety. Instead, you usually want to [pass JWT _claims_ to subgraphs](#example-forwarding-claims-to-subgraphs-as-headers) to enable fine-grained access control. +Because the GraphOS Router handles validating incoming JWTs, you rarely need to pass those JWTs to individual subgraphs in their entirety. Instead, you usually want to [pass JWT _claims_ to subgraphs](#example-forwarding-claims-to-subgraphs-as-headers) to enable fine-grained access control. -If you _do_ need to pass entire JWTs to subgraphs, you can do so via the Apollo Router's general-purpose [HTTP header propagation settings](./header-propagation). +If you _do_ need to pass entire JWTs to subgraphs, you can do so via the GraphOS Router's general-purpose [HTTP header propagation settings](./header-propagation). ## Observability diff --git a/docs/source/configuration/authn-subgraph.mdx b/docs/source/configuration/authn-subgraph.mdx index c9f1a3c378..d138e981d7 100644 --- a/docs/source/configuration/authn-subgraph.mdx +++ b/docs/source/configuration/authn-subgraph.mdx @@ -1,13 +1,13 @@ --- -title: Subgraph Authentication in the Apollo Router +title: Subgraph Authentication subtitle: Implement subgraph authentication using AWS SigV4 -description: Secure communication to AWS subgraphs via the Apollo Router using AWS Signature Version 4 (SigV4). +description: Secure communication to AWS subgraphs via the Apollo GraphOS Router or Apollo Router Core using AWS Signature Version 4 (SigV4). minVersion: 1.27.0 --- -The Apollo Router supports subgraph request authentication and key rotation via [AWS Signature Version 4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) (SigV4). +The GraphOS Router and Apollo Router Core support subgraph request authentication and key rotation via [AWS Signature Version 4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) (SigV4). -This allows you to secure communication to AWS subgraphs by making sure a subgraph request was made by the Apollo Router, and the payload hasn't been tampered with. +This allows you to secure communication to AWS subgraphs by making sure a subgraph request was made by the router, and the payload hasn't been tampered with. We have tested the feature against the following services: - AWS Lambda URL diff --git a/docs/source/configuration/authorization.mdx b/docs/source/configuration/authorization.mdx index 3566babead..cd241d1d4a 100644 --- a/docs/source/configuration/authorization.mdx +++ b/docs/source/configuration/authorization.mdx @@ -1,7 +1,7 @@ --- -title: Authorization in the Apollo Router +title: Authorization in the GraphOS Router subtitle: Strengthen subgraph security with a centralized governance layer -description: Enforce authorization in the Apollo Router with the @requireScopes, @authenticated, and @policy directives. +description: Enforce authorization in the GraphOS Router with the @requireScopes, @authenticated, and @policy directives. --- @@ -16,7 +16,7 @@ Services may have their own access controls, but enforcing authorization _in the flowchart LR; clients(Client); subgraph Router[" "] - router(["Apollo Router"]); + router(["GraphOS Router"]); serviceB[Users
API]; serviceC[Posts
API]; end @@ -30,7 +30,7 @@ Services may have their own access controls, but enforcing authorization _in the flowchart LR; clients(Client); subgraph Router[" "] - router(["Apollo Router"]); + router(["GraphOS Router"]); serviceB[Users
API]; serviceC[Posts
API]; end @@ -49,7 +49,7 @@ Services may have their own access controls, but enforcing authorization _in the clients(Client); Level2:::padding subgraph Level1["
🔐 Router layer                                                   "] - router(["Apollo Router"]); + router(["GraphOS Router"]); subgraph Level2["🔐 Service layer"] serviceB[Users
API]; serviceC[Posts
API]; @@ -76,7 +76,7 @@ To learn more about why authorization is ideal at the router layer, watch Andrew ## How access control works -The Apollo Router provides access controls via **authorization directives** that define access to specific fields and types across your supergraph: +The GraphOS Router provides access controls via **authorization directives** that define access to specific fields and types across your supergraph: - The [`@requiresScopes`](#requiresscopes) directive allows granular access control through the scopes you define. - The [`@authenticated`](#authenticated) directive allows access to the annotated field or type for _authenticated requests only_. @@ -106,12 +106,12 @@ The router then enforces these directives on all incoming requests. -Only the Apollo Router supports authorization directives—[`@apollo/gateway`](/federation/v1/gateway/) does _not_. Check out the [migration guide](../migrating-from-gateway/) if you'd like to use them. +Only the GraphOS Router supports authorization directives—[`@apollo/gateway`](/federation/v1/gateway/) does _not_. Check out the [migration guide](../migrating-from-gateway/) if you'd like to use them. Before using the authorization directives in your subgraph schemas, you must: -- Validate that your Apollo Router uses version `1.29.1` or later and is [connected to your GraphOS Enterprise organization](../enterprise-features/#enabling-enterprise-features) +- Validate that your GraphOS Router uses version `1.29.1` or later and is [connected to your GraphOS Enterprise organization](../enterprise-features/#enabling-enterprise-features) - Include **[claims](#configure-request-claims)** in requests made to the router (for `@authenticated` and `@requiresScopes`) ### Configure request claims @@ -120,8 +120,8 @@ Claims are the individual details of a request's authentication and scope. They To provide the router with the claims it needs, you must either configure JSON Web Token (JWT) authentication or add an external coprocessor that adds claims to a request's context. In some cases (explained below), you may require both. -- **JWT authentication configuration**: If you configure [JWT authentication](./authn-jwt), the Apollo Router [automatically adds a JWT token's claims](./authn-jwt#working-with-jwt-claims) to the request's context at the `apollo_authentication::JWT::claims` key. -- **Adding claims via coprocessor**: If you can't use JWT authentication, you can [add claims with a coprocessor](../customizations/coprocessor#adding-authorization-claims-via-coprocessor). Coprocessors let you hook into the Apollo Router's request-handling lifecycle with custom code. +- **JWT authentication configuration**: If you configure [JWT authentication](./authn-jwt), the GraphOS Router [automatically adds a JWT token's claims](./authn-jwt#working-with-jwt-claims) to the request's context at the `apollo_authentication::JWT::claims` key. +- **Adding claims via coprocessor**: If you can't use JWT authentication, you can [add claims with a coprocessor](../customizations/coprocessor#adding-authorization-claims-via-coprocessor). Coprocessors let you hook into the GraphOS Router's request-handling lifecycle with custom code. - **Augmenting JWT claims via coprocessor**: Your authorization policies may require information beyond what your JSON web tokens provide. For example, a token's claims may include user IDs, which you then use to look up user roles. For situations like this, you can [augment the claims](./authn-jwt#claim-augmentation-via-coprocessors) from your JSON web tokens with coprocessors. ## Authorization directives @@ -497,7 +497,7 @@ Using the `@policy` directive requires a [Supergraph plugin](../customizations/o An overview of how `@policy` is processed through the router's request lifecycle: -* At the [`RouterService` level](../customizations/overview#the-request-lifecycle), the Apollo Router extracts the list of policies relevant to a request from the schema and then stores them in the request's context in `apollo_authorization::policies::required` as a map `policy -> null|true|false`. +* At the [`RouterService` level](../customizations/overview#the-request-lifecycle), the GraphOS Router extracts the list of policies relevant to a request from the schema and then stores them in the request's context in `apollo_authorization::policies::required` as a map `policy -> null|true|false`. * At the `SupergraphService` level, you must provide a Rhai script or coprocessor to evaluate the map. If the policy is validated, the script or coprocessor should set its value to `true` or otherwise set it to `false`. If the value is left to `null`, it will be treated as `false` by the router. Afterward, the router filters the requests' types and fields to only those where the policy is `true`. @@ -966,4 +966,4 @@ authorization: ## Related topics -* [Authenticating requests with the Apollo Router](/technotes/TN0004-router-authentication/) +* [Authenticating requests with the GraphOS Router](/technotes/TN0004-router-authentication/) diff --git a/docs/source/configuration/cors.mdx b/docs/source/configuration/cors.mdx index 43ac8f20ee..45e331f2ba 100644 --- a/docs/source/configuration/cors.mdx +++ b/docs/source/configuration/cors.mdx @@ -1,19 +1,19 @@ --- -title: Configuring CORS in the Apollo Router +title: Configuring CORS subtitle: Control browser access to your router -description: Manage browser access to your Apollo Router with CORS configuration options, including origin whitelisting, wildcard origins, and credential passing. +description: Manage browser access to your Apollo GraphOS Router or Apollo Router Core with CORS configuration options, including origin whitelisting, wildcard origins, and credential passing. --- -**This article describes CORS configuration that's specific to the Apollo Router**. For a more general introduction to CORS and common considerations, see the following sections: +**This article describes CORS configuration that's specific to the GraphOS Router and Apollo Router Core**. For a more general introduction to CORS and common considerations, see the following sections: * [Why use CORS?](/apollo-server/security/cors#why-use-cors) * [Choosing CORS options for your project](/apollo-server/security/cors#choosing-cors-options-for-your-project) -By default, the Apollo Router enables _only_ GraphOS Studio to initiate browser connections to it. If your supergraph serves data to other browser-based applications, you need to do one of the following in the `cors` section of your router's [YAML config file](./overview/#yaml-config-file): +By default, the router enables _only_ GraphOS Studio to initiate browser connections to it. If your supergraph serves data to other browser-based applications, you need to do one of the following in the `cors` section of your router's [YAML config file](./overview/#yaml-config-file): * Add the origins of those web applications to the router's list of allowed `origins`. * Use this option if there is a known, finite list of web applications that consume your supergraph. @@ -62,7 +62,7 @@ If your router requires requests to [include a user's credentials](https://devel You can enable credentials with CORS by setting the [`Access-Control-Allow-Credentials`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials) HTTP header to `true`. -To allow browsers to pass credentials to the Apollo Router, set `allow_credentials` to `true`, like so: +To allow browsers to pass credentials to the router, set `allow_credentials` to `true`, like so: ```yaml {6} title="router.yaml" cors: @@ -93,7 +93,7 @@ For examples of sending cookies and authorization headers from Apollo Client, se ## All `cors` options -The following snippet shows all CORS configuration defaults for the Apollo Router: +The following snippet shows all CORS configuration defaults for the router: ```yaml title="router.yaml" # diff --git a/docs/source/configuration/csrf.mdx b/docs/source/configuration/csrf.mdx index 4a9860e781..b94dd53da5 100644 --- a/docs/source/configuration/csrf.mdx +++ b/docs/source/configuration/csrf.mdx @@ -1,13 +1,13 @@ --- title: Cross-Site Request Forgery (CSRF) Prevention -subtitle: Prevent CSRF attacks in the Apollo Router -description: Prevent cross-site request forgery (CSRF) attacks in the Apollo Router. +subtitle: Prevent CSRF attacks in the router +description: Prevent cross-site request forgery (CSRF) attacks in the Apollo GraphOS Router or Apollo Router Core. minVersion: 0.9.0 --- ## About CSRF -[Cross-site request forgery (CSRF)](https://owasp.org/www-community/attacks/csrf) attacks use side effects of ["simple"](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests) requests to execute GraphQL operations from requests sent by sites that shouldn't be allowed to communicate with your server, based on your Apollo Router's [CORS policy](./cors/). +[Cross-site request forgery (CSRF)](https://owasp.org/www-community/attacks/csrf) attacks use side effects of ["simple"](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests) requests to execute GraphQL operations from requests sent by sites that shouldn't be allowed to communicate with your server, based on the [CORS policy](./cors/) of your GraphOS Router or Apollo Router Core. Your router's CORS policy enables you to control which websites can talk to your server. In most cases, the browser checks your server's CORS policy by sending a [preflight request](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) before sending the actual operation. This is a separate HTTP request. Unlike most HTTP requests (which use the `GET` or `POST` method), this request uses a method called `OPTIONS`. The browser sends an `Origin` header, along with some other headers that start with `Access-Control-`. These headers describe the kind of request that the potentially untrusted JavaScript wants to make. Your server returns a response with `Access-Control-*` headers describing its policies (as described above), and the browser uses that response to decide whether it's OK to send the real request. Processing the `OPTIONS` preflight request never actually executes GraphQL operations. @@ -23,13 +23,13 @@ To avoid CSRF and XS-Search attacks, GraphQL servers should refuse to execute an The most important rule for whether or not a request is "simple" is whether it tries to set arbitrary HTTP request headers. Any request that sets the `Content-Type` header to `application/json` (or anything other than a list of three particular values) cannot be a simple request, and thus it must be preflighted. Because all `POST` requests recognized by Apollo Server must contain a `Content-Type` header specifying `application/json`, we can be confident that they are not simple requests and that if they come from a browser, they have been preflighted. -However, the Apollo Router also handles `GET` requests which do not require a `Content-Type` header, so they can potentially be simple requests. So how can we ensure that we only execute `GET` requests that are _not_ simple requests? If we require the request to include an HTTP header that is never set automatically by the browser, then that is sufficient: requests that set HTTP headers other than the handful defined in the spec must be preflighted. +However, the router also handles `GET` requests which do not require a `Content-Type` header, so they can potentially be simple requests. So how can we ensure that we only execute `GET` requests that are _not_ simple requests? If we require the request to include an HTTP header that is never set automatically by the browser, then that is sufficient: requests that set HTTP headers other than the handful defined in the spec must be preflighted. ## Configuring CSRF prevention in the router ### Enable CSRF prevention -The Apollo Router **enables CSRF prevention by default**. When this feature is enabled, the router only executes GraphQL operations if at least one of the following conditions is true: +The router **enables CSRF prevention by default**. When this feature is enabled, the router only executes GraphQL operations if at least one of the following conditions is true: - The incoming request includes a `Content-Type` header that specifies a type other than `text/plain`, `application/x-www-form-urlencoded`, or `multipart/form-data`. @@ -69,11 +69,11 @@ The check for `Content-Type` remains the same. -We highly recommend that you keep CSRF prevention enabled in the Apollo Router. +We highly recommend that you keep CSRF prevention enabled in your router. -Disabling CSRF in the Apollo Router might be appropriate for a GraphQL server that only contains public data and allows no mutation, or on a closed private network where browsers cannot reach untrusted websites. +Disabling CSRF in the router might be appropriate for a GraphQL server that only contains public data and allows no mutation, or on a closed private network where browsers cannot reach untrusted websites. To disable CSRF prevention in the router, set `csrf.unsafe_disabled` to `true`: diff --git a/docs/source/configuration/distributed-caching.mdx b/docs/source/configuration/distributed-caching.mdx index 3938f832e7..2890cad126 100644 --- a/docs/source/configuration/distributed-caching.mdx +++ b/docs/source/configuration/distributed-caching.mdx @@ -1,14 +1,14 @@ --- -title: Distributed Caching for the Apollo Router +title: Distributed Caching for the GraphOS Router subtitle: Configure Redis-backed caching for query plans and APQ -description: Distributed caching for Apollo Router with GraphOS Enterprise. Configure a Redis-backed cache for query plans and automatic persisted queries (APQ). +description: Distributed caching for GraphOS Router with GraphOS Enterprise. Configure a Redis-backed cache for query plans and automatic persisted queries (APQ). --- import RedisTLS from '../../shared/redis-tls.mdx' -If you have multiple Apollo Router instances, those instances can share a Redis-backed cache for their query plans and automatic persisted queries (APQ). This means that if _any_ of your router instances caches a particular value, _all_ of your instances can look up that value to significantly improve responsiveness. For more details on query plans and APQ, see the article on [in-memory caching](./in-memory-caching). +If you have multiple GraphOS Router instances, those instances can share a Redis-backed cache for their query plans and automatic persisted queries (APQ). This means that if _any_ of your router instances caches a particular value, _all_ of your instances can look up that value to significantly improve responsiveness. For more details on query plans and APQ, see the article on [in-memory caching](./in-memory-caching). ## Prerequisites @@ -150,7 +150,7 @@ The `ttl` option defines the default global expiration for Redis entries. For AP ### Namespace -When using the same Redis instance for multiple puposes, the `namespace` option defines a prefix for all the keys defined by the router. +When using the same Redis instance for multiple purposes, the `namespace` option defines a prefix for all the keys defined by the router. ### TLS @@ -158,8 +158,8 @@ When using the same Redis instance for multiple puposes, the `namespace` option ### Required to start -When active, the `required_to_start` option will prevent the Router from starting if it cannot connect to Redis. By default, the Router will still start without a connection to Redis, which would result in only using the in-memory cache for APQ and query planning, and entity caching sending the requests to subgraphs undisturbed. +When active, the `required_to_start` option will prevent the router from starting if it cannot connect to Redis. By default, the router will still start without a connection to Redis, which would result in only using the in-memory cache for APQ and query planning, and entity caching sending the requests to subgraphs undisturbed. ### Reset TTL -When this option is active, accessing a cache entry in Redis will reset its expiration. \ No newline at end of file +When this option is active, accessing a cache entry in Redis will reset its expiration. diff --git a/docs/source/configuration/entity-caching.mdx b/docs/source/configuration/entity-caching.mdx index 04cad8e25f..655d61dbcf 100644 --- a/docs/source/configuration/entity-caching.mdx +++ b/docs/source/configuration/entity-caching.mdx @@ -1,7 +1,7 @@ --- -title: Subgraph Entity Caching for the Apollo Router +title: Subgraph Entity Caching for the GraphOS Router subtitle: Configure Redis-backed caching for entities -description: Subgraph entity caching for Apollo Router with GraphOS Enterprise. Cache and reuse individual entities across queries. +description: Subgraph entity caching for GraphOS Router with GraphOS Enterprise. Cache and reuse individual entities across queries. minVersion: 1.40.0 --- @@ -9,11 +9,11 @@ minVersion: 1.40.0 -Learn how the Apollo Router can cache subgraph query responses using Redis to improve your query latency for entities in the supergraph. +Learn how the GraphOS Router can cache subgraph query responses using Redis to improve your query latency for entities in the supergraph. ## Overview -An entity gets its fields from one or more subgraphs. To respond to a client request for an entity, the Apollo Router must make multiple subgraph requests. Different clients requesting the same entity can make redundant, identical subgraph requests. +An entity gets its fields from one or more subgraphs. To respond to a client request for an entity, the GraphOS Router must make multiple subgraph requests. Different clients requesting the same entity can make redundant, identical subgraph requests. Entity caching enables the router to respond to identical subgraph queries with cached subgraph responses. The router uses Redis to cache data from subgraph query responses. Because cached data is keyed per subgraph and entity, different clients making the same client query—with the same or different query arguments—hit the same cache entries of subgraph response data. @@ -63,11 +63,11 @@ With entity caching enabled for this example, the router can: ## Use entity caching -Follow this guide to enable and configure entity caching in the Apollo Router. +Follow this guide to enable and configure entity caching in the GraphOS Router. ### Prerequisites -To use entity caching in the Apollo Router, you must set up: +To use entity caching in the GraphOS Router, you must set up: - A Redis instance or cluster that your router instances can communicate with - A [GraphOS Enterprise plan](https://www.apollographql.com/pricing/) that [connects your router to GraphOS](./overview/#environment-variables). @@ -105,7 +105,7 @@ preview_entity_cache: ### Configure time to live (TTL) -Besides configuring a global TTL for all the entries in Redis, the Apollo Router also honors the [`Cache-Control` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) returned with the subgraph response. It generates a `Cache-Control` header for the client response by aggregating the TTL information from all response parts. +Besides configuring a global TTL for all the entries in Redis, the GraphOS Router also honors the [`Cache-Control` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) returned with the subgraph response. It generates a `Cache-Control` header for the client response by aggregating the TTL information from all response parts. A TTL has to be configured for all subgraphs using entity caching, either defined in the per subgraph configuration or inherited from the global configuration. ### Customize Redis cache key diff --git a/docs/source/configuration/header-propagation.mdx b/docs/source/configuration/header-propagation.mdx index 2dfc151548..686f269552 100644 --- a/docs/source/configuration/header-propagation.mdx +++ b/docs/source/configuration/header-propagation.mdx @@ -1,10 +1,10 @@ --- -title: Header Propogation +title: Header Propagation subtitle: Configure HTTP header propagation to subgraphs -description: Configure which HTTP headers the Apollo Router sends to which subgraphs. Define per-subgraph header rules, along with rules that apply to all subgraphs. +description: Configure which HTTP headers the Apollo GraphOS Router or Apollo Router Core sends to which subgraphs. Define per-subgraph header rules, along with rules that apply to all subgraphs. --- -You can configure which HTTP headers the Apollo Router includes in its requests to each of your subgraphs. You can define per-subgraph header rules, along with rules that apply to _all_ subgraphs. +You can configure which HTTP headers the GraphOS Router or Apollo Route Core includes in its requests to each of your subgraphs. You can define per-subgraph header rules, along with rules that apply to _all_ subgraphs. You define header rules in your [YAML configuration file](./overview/#yaml-config-file), like so: @@ -27,7 +27,7 @@ headers: ## Supported header rules -The Apollo Router supports the following types of header rules: +The router supports the following types of header rules: ### `propagate` @@ -40,7 +40,11 @@ You can specify which headers to propagate based on a matching [regex pattern](h matching: .* ``` -> **Note:** The Apollo Router _never_ propagates so-called [hop-by-hop headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#hop-by-hop_headers) (such as `Content-Length`) when propagating by pattern. + + +The router _never_ propagates so-called [hop-by-hop headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#hop-by-hop_headers) (such as `Content-Length`) when propagating by pattern. + + Alternatively, you can provide a static string via the `named` option. These `named` configurations have additional flexibility, because they support the following options: diff --git a/docs/source/configuration/health-checks.mdx b/docs/source/configuration/health-checks.mdx index 8d0bfd3dba..e6f54857d6 100644 --- a/docs/source/configuration/health-checks.mdx +++ b/docs/source/configuration/health-checks.mdx @@ -1,12 +1,12 @@ --- -title: Health Checks in the Apollo Router +title: Health Checks subtitle: Determining the router's status -description: Learn how to run health checks to determine whether an Apollo Router is available and ready to start serving traffic. +description: Learn how to run health checks to determine whether an Apollo GraphOS Router or Apollo Router Core is available and ready to start serving traffic. --- Health checks are often used by load balancers to determine whether a server is available and ready to start serving traffic. -The Apollo Router supports a basic HTTP-level health check. This is enabled by default and is served on port `8088` at the URL path `/health`. This returns a `200` status code if the HTTP server is successfully serving. +GraphOS Router and Apollo Router Core support a basic HTTP-level health check. This is enabled by default and is served on port `8088` at the URL path `/health`. This returns a `200` status code if the HTTP server is successfully serving. You can change this by setting `health_check`: ```yaml title="router.yaml" health_check: @@ -33,7 +33,7 @@ health_check: ## Testing with `curl` -The following example demonstrates using the `curl` command to send a basic health check query to an Apollo Router instance running at `127.0.0.1:4000`: +The following example demonstrates using the `curl` command to send a basic health check query to a router instance running at `127.0.0.1:4000`: ```sh $ curl -v "http://127.0.0.1:8088/health" diff --git a/docs/source/configuration/in-memory-caching.mdx b/docs/source/configuration/in-memory-caching.mdx index 4e483906a6..2acf126c59 100644 --- a/docs/source/configuration/in-memory-caching.mdx +++ b/docs/source/configuration/in-memory-caching.mdx @@ -1,10 +1,10 @@ --- -title: In-Memory Caching in the Apollo Router -subtitle: Configure caching for query plans and automatic persisted queries -description: Configure the Apollo Router's in-memory caching for improved performance. Configure query plans and automatic persisted queries caching. +title: In-Memory Caching +subtitle: Configure router caching for query plans and automatic persisted queries +description: Configure in-memory caching for improved performance in Apollo GraphOS Router or Apollo Router Core. Configure query plans and automatic persisted queries caching. --- -The Apollo Router uses an in-memory LRU cache to store the following data: +Both GraphOS Router and Apollo Router Core use an in-memory LRU cache to store the following data: - [Generated query plans](#caching-query-plans) - [Automatic persisted queries (APQ)](#caching-automatic-persisted-queries-apq) @@ -14,13 +14,13 @@ You can configure certain caching behaviors for generated query plans and APQ (b -If you have a GraphOS Enterprise plan, you can also configure a Redis-backed _distributed_ cache that enables multiple router instances to share cached values. For details, see [Distributed caching in the Apollo Router](./distributed-caching/). +If you have a GraphOS Enterprise plan, you can also configure a Redis-backed _distributed_ cache that enables multiple router instances to share cached values. For details, see [Distributed caching in the GraphOS Router](./distributed-caching/). ## Performance improvements vs stability -The Router is a highly scalable and low-latency runtime. Even with all caching **disabled**, the time to process operations and query plans will be very minimal (nanoseconds to milliseconds) when compared to the overall supergraph request, except in the edge cases of extremely large operations and supergraphs. Caching offers stability to those running a large graph so that your overhead for given operations stays consistent, not that it dramatically improves. If you would like to validate the performance wins of operation caching, check out the [traces and metrics in the Router](/router/configuration/telemetry/instrumentation/standard-instruments#performance) to take measurements before and after. In extremely large edge cases though, we have seen the cache save 2-10x time to create the query plan, which is still a small part of the overall request. +The router is a highly scalable and low-latency runtime. Even with all caching **disabled**, the time to process operations and query plans will be very minimal (nanoseconds to milliseconds) when compared to the overall supergraph request, except in the edge cases of extremely large operations and supergraphs. Caching offers stability to those running a large graph so that your overhead for given operations stays consistent, not that it dramatically improves. If you would like to validate the performance wins of operation caching, check out the [traces and metrics in the router](/router/configuration/telemetry/instrumentation/standard-instruments#performance) to take measurements before and after. In extremely large edge cases though, we have seen the cache save 2-10x time to create the query plan, which is still a small part of the overall request. ## Caching query plans @@ -28,7 +28,7 @@ Whenever your router receives an incoming GraphQL operation, it generates a [que By caching previously generated query plans, your router can _skip_ generating them _again_ if a client later sends the exact same operation. This improves your router's responsiveness. -The Apollo Router enables query plan caching by default. In your router's [YAML config file](./overview/#yaml-config-file), you can configure the maximum number of query plan entries in the cache like so: +The GraphOS Router enables query plan caching by default. In your router's [YAML config file](./overview/#yaml-config-file), you can configure the maximum number of query plan entries in the cache like so: ```yaml title="router.yaml" supergraph: @@ -54,13 +54,13 @@ supergraph: When loading a new schema, a query plan might change for some queries, so cached query plans cannot be reused. -To prevent increased latency upon query plan cache invalidation, the Router precomputes query plans for: +To prevent increased latency upon query plan cache invalidation, the router precomputes query plans for: * The most used queries from the cache. * The entire list of persisted queries. -Precomputed plans will be cached before the Router switches traffic over to the new schema. +Precomputed plans will be cached before the router switches traffic over to the new schema. -By default, the Router warms up the cache with 30% of the queries already in cache, but it can be configured as follows: +By default, the router warms up the cache with 30% of the queries already in cache, but it can be configured as follows: ```yaml title="router.yaml" supergraph: @@ -87,7 +87,7 @@ then look at `apollo_router_schema_loading_time` and `apollo.router.query_planni #### Cache warm-up with distributed caching -If the Router is using distributed caching for query plans, the warm-up phase will also store the new query plans in Redis. Since all Router instances might have the same distributions of queries in their in-memory cache, the list of queries is shuffled before warm-up, so each Router instance can plan queries in a different order and share their results through the cache. +If the router is using distributed caching for query plans, the warm-up phase will also store the new query plans in Redis. Since all Router instances might have the same distributions of queries in their in-memory cache, the list of queries is shuffled before warm-up, so each Router instance can plan queries in a different order and share their results through the cache. #### Schema aware query hashing @@ -106,7 +106,7 @@ supergraph: [Automatic Persisted Queries (**APQ**)](/apollo-server/performance/apq/) enable GraphQL clients to send a server the _hash_ of their query string, _instead of_ sending the query string itself. When query strings are very large, this can significantly reduce network usage. -The Apollo Router supports using APQ in its communications with both clients _and_ subgraphs: +The router supports using APQ in its communications with both clients _and_ subgraphs: - **In its communications with clients,** the router acts as a GraphQL _server_, because it _receives_ queries from clients. - **In its communications with subgraphs,** the router acts as a GraphQL _client_, because it _sends_ queries to subgraphs. @@ -115,7 +115,7 @@ Because the router's role differs between these two interactions, you configure ### APQ with clients -The Apollo Router enables APQ caching for client operations by default. In your router's [YAML config file](./overview/#yaml-config-file), you can configure the maximum number of APQ entries in the cache like so: +The router enables APQ caching for client operations by default. In your router's [YAML config file](./overview/#yaml-config-file), you can configure the maximum number of APQ entries in the cache like so: ```yaml title="router.yaml" apq: @@ -134,7 +134,7 @@ apq: ### APQ with subgraphs -By default, the Apollo Router does _not_ use APQ when sending queries to its subgraphs. +By default, the router does _not_ use APQ when sending queries to its subgraphs. In your router's [YAML config file](./overview/#yaml-config-file), you can configure this APQ support with a combination of global and per-subgraph settings: diff --git a/docs/source/configuration/operation-limits.mdx b/docs/source/configuration/operation-limits.mdx index d94a578485..da05ae4e54 100644 --- a/docs/source/configuration/operation-limits.mdx +++ b/docs/source/configuration/operation-limits.mdx @@ -1,7 +1,7 @@ --- -title: Enforcing Operation Limits in the Apollo Router +title: Enforcing Operation Limits in the GraphOS Router subtitle: Set constraints on depth, height, aliases, and root fields -description: Ensure your GraphQL operations are secure with Apollo Router's operation limits. Set constraints on depth, height, aliases, and root fields. +description: Ensure your GraphQL operations are secure with GraphOS Router's operation limits. Set constraints on depth, height, aliases, and root fields. --- @@ -10,7 +10,7 @@ You can define **operation limits** in your router's configuration to reject pot ## Setup -To use operation limits, you must run v1.17 or later of the Apollo Router. [Download the latest version.](../quickstart#download-options) +To use operation limits, you must run v1.17 or later of the GraphOS Router. [Download the latest version.](../quickstart#download-options) You define operation limits in your router's [YAML config file](./overview/#yaml-config-file), like so: diff --git a/docs/source/configuration/overview.mdx b/docs/source/configuration/overview.mdx index fe8b06d23e..d4bd85955b 100644 --- a/docs/source/configuration/overview.mdx +++ b/docs/source/configuration/overview.mdx @@ -1,16 +1,16 @@ --- -title: Configuring the Apollo Router -subtitle: With environment variables, command-line options, and YAML file configuration -description: Learn how to configure the Apollo Router with environment variables, command-line options and commands, and YAML configuration files. +title: Router Configuration +subtitle: Configure a router via environment variables, command-line options, and YAML +description: Learn how to configure the Apollo GraphOS Router or Apollo Router Core with environment variables, command-line options and commands, and YAML configuration files. --- import RedisTLS from '../../shared/redis-tls.mdx' -Learn how to customize the behavior of your Apollo Router with environment variables, command-line commands and options, and YAML file configuration. +Learn how to customize the behavior of your GraphOS Router or Apollo Router Core with environment variables, command-line commands and options, and YAML file configuration. ## Environment variables -If you're using the Apollo Router with [managed federation](/federation/managed-federation/overview/) and GraphOS, set these environment variables in the startup command: +If you're using the GraphOS Router with [managed federation](/federation/managed-federation/overview/) and GraphOS Studio, set these environment variables in the startup command: ```bash APOLLO_KEY="..." APOLLO_GRAPH_REF="..." ./router @@ -61,7 +61,7 @@ The [graph API key](/graphos/api-keys/#graph-api-keys) that the router should us ## Command-line options -After [installing the Apollo Router](../quickstart/) in your current working directory, you can run the Apollo Router with the following example command: +After [installing the Apollo Router Core](../quickstart/) in your current working directory, you can run the router with the following example command: ```bash ./router --config router.yaml --supergraph supergraph-schema.graphql @@ -89,7 +89,7 @@ This reference lists and describes the options supported by the `router` binary. -The Apollo Router's [supergraph schema](/federation/federated-types/overview/#supergraph-schema). Specified by absolute or relative path (`-s` / `--supergraph `, or `APOLLO_ROUTER_SUPERGRAPH_PATH`), or a comma-separated list of URLs (`APOLLO_ROUTER_SUPERGRAPH_URLS`). +The [supergraph schema](/federation/federated-types/overview/#supergraph-schema) of a router. Specified by absolute or relative path (`-s` / `--supergraph `, or `APOLLO_ROUTER_SUPERGRAPH_PATH`), or a comma-separated list of URLs (`APOLLO_ROUTER_SUPERGRAPH_URLS`). > 💡 Avoid embedding tokens in `APOLLO_ROUTER_SUPERGRAPH_URLS` because the URLs may appear in log messages. @@ -127,7 +127,7 @@ The absolute or relative path to the router's optional [YAML configuration file] ⚠️ **Do not set this option in production!** -If set, the Apollo Router runs in dev mode to help with local development. +If set, a router runs in dev mode to help with local development. [Learn more about dev mode.](#dev-mode-defaults) @@ -327,7 +327,7 @@ plugins: ## `config` subcommands -The Apollo Router provides a set of subcommands for interacting with its configuration. You run these subcommands with the following syntax: +GraphOS Router and Apollo Router Core provide a set of subcommands for interacting with its configuration. You run these subcommands with the following syntax: ``` ./router config schema @@ -367,7 +367,7 @@ Use this schema to enable [configuration awareness in your text editor](#configu -Takes a config file created for a _previous_ version of the Apollo Router and outputs the corresponding configuration for the _current_ version. +Takes a config file created for a _previous_ version of the router and outputs the corresponding configuration for the _current_ version. For details, see [Upgrading your router configuration](#upgrading-your-router-configuration). @@ -379,7 +379,7 @@ For details, see [Upgrading your router configuration](#upgrading-your-router-co ## YAML config file -The Apollo Router takes an optional YAML configuration file as input via the [`--config`](#-c----config) option: +GraphOS Router and Apollo Router Core take an optional YAML configuration file as input via the [`--config`](#-c----config) option: ```bash ./router --config router.yaml @@ -397,7 +397,7 @@ Enable your text editor to validate the format and content of your router YAML c ### Listen address -By default, the Apollo Router starts an HTTP server that listens on `127.0.0.1:4000`. You can specify a different address by setting `supergraph.listen`: +By default, the router starts an HTTP server that listens on `127.0.0.1:4000`. You can specify a different address by setting `supergraph.listen`: #### IPv4 @@ -469,13 +469,13 @@ supergraph: ### Debugging -- To configure logging, see [Logging in the Apollo Router](./telemetry/exporters/logging/overview). +- To configure logging, see [Logging in the router](./telemetry/exporters/logging/overview). - To configure the inclusion of subgraph errors, see [Subgraph error inclusion](./subgraph-error-inclusion). ### Landing pages -The Apollo Router can serve any of the following landing pages to browsers that visit its [endpoint path](#endpoint-path): +The router can serve any of the following landing pages to browsers that visit its [endpoint path](#endpoint-path): - A basic landing page that displays an example query `curl` command (default) @@ -517,7 +517,7 @@ The Apollo Router can serve any of the following landing pages to browsers that ### Subgraph routing URLs -By default, the Apollo Router obtains the routing URL for each of your subgraphs from the composed supergraph schema you provide it. In most cases, no additional configuration is required. The URL can use HTTP and HTTPS for network access to subgraph, or have the following shape for Unix sockets usage: `unix:///path/to/subgraph.sock` +By default, the router obtains the routing URL for each of your subgraphs from the composed supergraph schema you provide it. In most cases, no additional configuration is required. The URL can use HTTP and HTTPS for network access to subgraph, or have the following shape for Unix sockets usage: `unix:///path/to/subgraph.sock` However, if you _do_ need to override a particular subgraph's routing URL (for example, to handle changing network topography), you can do so with the `override_subgraph_url` option: @@ -535,17 +535,17 @@ If you need to override the subgraph URL at runtime on a per-request basis, you ### Caching -By default, the Apollo Router stores the following data in its in-memory cache to improve performance: +By default, the router stores the following data in its in-memory cache to improve performance: - Generated query plans - Automatic persisted queries (APQ) - Introspection responses -You can configure certain caching behaviors for generated query plans and APQ (but not introspection responses). For details, see [In-memory caching in the Apollo Router](./in-memory-caching/). +You can configure certain caching behaviors for generated query plans and APQ (but not introspection responses). For details, see [In-Memory Caching in the router](./in-memory-caching/). **If you have a GraphOS Enterprise plan:** -- You can configure a Redis-backed _distributed_ cache that enables multiple router instances to share cached values. For details, see [Distributed caching in the Apollo Router](./distributed-caching/). -- You can configure a Redis-backed _entity_ cache that enables a client query to retrieve cached entity data split between subgraph reponses. For details, see [Subgraph entity caching in the Apollo Router](./entity-caching/). +- You can configure a Redis-backed _distributed_ cache that enables multiple router instances to share cached values. For details, see [Distributed caching in the GraphOS Router](./distributed-caching/). +- You can configure a Redis-backed _entity_ cache that enables a client query to retrieve cached entity data split between subgraph reponses. For details, see [Subgraph entity caching in the GraphOS Router](./entity-caching/). @@ -853,7 +853,7 @@ You won't see an immediate change in checks behavior when you first turn on exte ### Safelisting with persisted queries -You can enhance your graph's security by maintaining a persisted query list (PQL), an operation safelist made by your first-party apps. As opposed to automatic persisted queries (APQ) where operations are automatically cached, operations must be preregistered to the PQL. Once configured, the router checks incoming requests against the PQL. +You can enhance your graph's security with GraphOS Router by maintaining a persisted query list (PQL), an operation safelist made by your first-party apps. As opposed to automatic persisted queries (APQ) where operations are automatically cached, operations must be preregistered to the PQL. Once configured, the router checks incoming requests against the PQL. See [Safelisting with persisted queries](./persisted-queries) for more information. @@ -863,23 +863,23 @@ See [Sending HTTP headers to subgraphs](./header-propagation/). ### Traffic shaping -To configure the shape of traffic between clients, routers, and subgraphs, see [Traffic shaping in the Apollo Router](./traffic-shaping). +To configure the shape of traffic between clients, routers, and subgraphs, see [Traffic shaping in the router](./traffic-shaping). ### Cross-Origin Resource Sharing (CORS) -See [Configuring CORS in the Apollo Router](./cors). +See [Configuring CORS in the router](./cors). ### Defer support -See [Apollo Router support for `@defer`](../executing-operations/defer-support/#disabling-defer). +See [router support for `@defer`](../executing-operations/defer-support/#disabling-defer). ### Query batching support -See [Apollo Router's _experimental_ support for query batching](../executing-operations/query-batching). +See [GraphOS Router's support for query batching](../executing-operations/query-batching). ### Subscription support -See [GraphQL subscriptions in the Apollo Router](../executing-operations/subscription-support/#router-setup). +See [GraphQL subscriptions in the GraphOS Router](../executing-operations/subscription-support/#router-setup). ### Authorization support @@ -889,11 +889,11 @@ See [GraphQL subscriptions in the Apollo Router](../executing-operations/subscri ### JWT authentication -To enable and configure JWT authentication, see [JWT authentication in the Apollo Router](./authn-jwt). +To enable and configure JWT authentication, see [JWT authentication in the GraphOS Router](./authn-jwt). ### Cross-site request forgery (CSRF) prevention -To configure CSRF prevention, see [CSRF prevention in the Apollo Router](./csrf). +To configure CSRF prevention, see [CSRF prevention in the router](./csrf). ### Subgraph authentication @@ -901,17 +901,17 @@ To configure subgraph authentication with AWS SigV4, see a [configuration exampl ### External coprocessing -See [External coprocessing in the Apollo Router](../customizations/coprocessor/). +See [External coprocessing in the GraphOS Router](../customizations/coprocessor/). ### Telemetry and monitoring -The Apollo Router supports standard and custom instrumentation to collect telemetry data from its request and response processing pipeline to produce logs, metrics and traces to export. +The router supports standard and custom instrumentation to collect telemetry data from its request and response processing pipeline to produce logs, metrics and traces to export. -See the [Apollo Router telemetry overview](./telemetry/overview). +See the [router telemetry overview](./telemetry/overview). ### TLS -The Apollo Router supports TLS to authenticate and encrypt communications, both on the client side and the subgraph side. It works automatically on the subgraph side if the subgraph URL starts with `https://`. +The router supports TLS to authenticate and encrypt communications, both on the client side and the subgraph side. It works automatically on the subgraph side if the subgraph URL starts with `https://`. TLS support is configured in the `tls` section, under the `supergraph` key for the client side, and the `subgraph` key for the subgraph side, with configuration possible for all subgraphs and overriding per subgraph. @@ -1025,7 +1025,7 @@ tls: ### Request limits -The Apollo Router supports enforcing three types of request limits for enhanced security: +The GraphOS Router supports enforcing three types of request limits for enhanced security: - Network-based limits - Lexical, parser-based limits @@ -1066,7 +1066,7 @@ The default value is `2000000` bytes, 2 MB. Before increasing this limit significantly consider testing performance in an environment similar to your production, especially if some clients are untrusted. -Many concurrent large requests could cause the Router to run out of memory. +Many concurrent large requests could cause the router to run out of memory. #### Parser-based limits @@ -1103,27 +1103,21 @@ fragment ProductVariation on Product { Note that the router calculates the recursion depth for each operation and fragment _separately_. Even if a fragment is included in an operation, that fragment's recursion depth does not contribute to the _operation's_ recursion depth. - - -In versions of the Apollo Router prior to 1.17, this limit was defined via the config option `experimental_parser_recursion_limit`. - - - ### Demand control See [Demand Control](../executing-operations/demand-control) to learn how to analyze the cost of operations and to reject requests with operations that exceed customizable cost limits. ### Early cancel -Up until [Apollo Router 1.43.1](https://github.com/apollographql/router/releases/tag/v1.43.1), when the client closed the connection without waiting for the response, the entire request was cancelled and did not go through the entire pipeline. Since this causes issues with request monitoring, the Router introduced a new behaviour in 1.43.1. Now, the entire pipeline is executed if the request is detected as cancelled, but subgraph requests are not actually done. The response will be reported with the `499` status code, but not actually sent to the client. -To go back to the previous behaviour of immediately cancelling the request, the following configuration can be used: +Up until [Apollo Router Core v1.43.1](https://github.com/apollographql/router/releases/tag/v1.43.1), when the client closed the connection without waiting for the response, the entire request was cancelled and did not go through the entire pipeline. Since this causes issues with request monitoring, the router introduced a new behavior in 1.43.1. Now, the entire pipeline is executed if the request is detected as cancelled, but subgraph requests are not actually done. The response will be reported with the `499` status code, but not actually sent to the client. +To go back to the previous behavior of immediately cancelling the request, the following configuration can be used: ```yaml supergraph: early_cancel: true ``` -Additionally, since 1.43.1, the Apollo Router can show a log when it detects that the client canceled the request. This log can be activated with: +Additionally, since v1.43.1, the router can show a log when it detects that the client canceled the request. This log can be activated with: ```yaml title="router.yaml" supergraph: @@ -1133,7 +1127,7 @@ supergraph: ### Plugins -You can customize the Apollo Router's behavior with [plugins](../customizations/overview). Each plugin can have its own section in the configuration file with arbitrary values: +You can customize the router's behavior with [plugins](../customizations/overview). Each plugin can have its own section in the configuration file with arbitrary values: ```yaml {4,8} title="example-plugin-router.yaml" plugins: @@ -1146,7 +1140,7 @@ plugins: You can reference variables directly in your YAML config file. This is useful for referencing secrets without including them in the file. -Currently, the Apollo Router supports expansion of environment variables and file paths. Corresponding variables are prefixed with `env.` and `file.`, respectively. +Currently, the router supports expansion of environment variables and file paths. Corresponding variables are prefixed with `env.` and `file.`, respectively. The router uses Unix-style expansion. Here are some examples: @@ -1167,14 +1161,14 @@ example: ### Fragment reuse and generation -By default, the Apollo Router will attempt to reuse fragments from the original query while forming subgraph requests. This behavior can be disabled by setting the option to `false`: +By default, the router will attempt to reuse fragments from the original query while forming subgraph requests. This behavior can be disabled by setting the option to `false`: ```yaml supergraph: experimental_reuse_query_fragments: false ``` -Alternatively, the Apollo Router can be configured to _generate_ fragments for subgraph requests. When set to `true`, the Apollo Router will extract _inline fragments only_ into fragment definitions before sending queries to subgraphs. This can significantly reduce the size of the query sent to subgraphs, but may increase the time it takes for planning. Note that this option and `experimental_reuse_query_fragments` are mutually exclusive; if both are explicitly set to `true`, `generate_query_fragments` will take precedence. +Alternatively, the router can be configured to _generate_ fragments for subgraph requests. When set to `true`, the router will extract _inline fragments only_ into fragment definitions before sending queries to subgraphs. This can significantly reduce the size of the query sent to subgraphs, but may increase the time it takes for planning. Note that this option and `experimental_reuse_query_fragments` are mutually exclusive; if both are explicitly set to `true`, `generate_query_fragments` will take precedence. ```yaml supergraph: @@ -1202,7 +1196,7 @@ Here, the `name` and `value` entries under `&insert_custom_header` are reused un ## Configuration awareness in your text editor -The Apollo Router can generate a JSON schema for config validation in your text editor. This schema helps you format the YAML file correctly and also provides content assist. +The router can generate a JSON schema for config validation in your text editor. This schema helps you format the YAML file correctly and also provides content assist. Generate the schema with the following command: @@ -1220,7 +1214,7 @@ After you generate the schema, configure your text editor. Here are the instruct ## Upgrading your router configuration -New releases of the Apollo Router might introduce breaking changes to the [YAML config file's](#yaml-config-file) expected format, usually to extend existing functionality or improve usability. +New releases of the router might introduce breaking changes to the [YAML config file's](#yaml-config-file) expected format, usually to extend existing functionality or improve usability. **If you run a new version of your router with a configuration file that it no longer supports:** diff --git a/docs/source/configuration/persisted-queries.mdx b/docs/source/configuration/persisted-queries.mdx index bb476c53ad..677582a01c 100644 --- a/docs/source/configuration/persisted-queries.mdx +++ b/docs/source/configuration/persisted-queries.mdx @@ -11,7 +11,7 @@ minVersion: 1.25.0 ## Differences from automatic persisted queries -The Apollo Router also supports a related feature called [automatic persisted queries](./in-memory-caching#caching-automatic-persisted-queries-apq) (APQ). With APQ, clients can execute a GraphQL operation by sending the SHA256 hash of its operation string instead of the entire string. **APQ doesn't support safelisting** because the router updates its APQ cache over time with _any_ operations it receives. +The Apollo Router Core also supports a related feature called [automatic persisted queries](./in-memory-caching#caching-automatic-persisted-queries-apq) (APQ). With APQ, clients can execute a GraphQL operation by sending the SHA256 hash of its operation string instead of the entire string. **APQ doesn't support safelisting** because the router updates its APQ cache over time with _any_ operations it receives. For more details on differences between APQ and this feature, see the [GraphOS persisted queries documentation](/graphos/operations/persisted-queries#differences-from-automatic-persisted-queries). @@ -138,4 +138,4 @@ To enable safelisting, you _must_ turn off [automatic persisted queries](./in-me ## Limitations -* **Unsupported with offline license**. An Apollo Router using an [offline Enterprise license](../enterprise-features/#offline-enterprise-license) cannot use safelisting with persisted queries. The feature relies on Apollo Uplink to fetch persisted query manifests, so it doesn't work as designed when the router is disconnected from Uplink. +* **Unsupported with offline license**. An GraphOS Router using an [offline Enterprise license](../enterprise-features/#offline-enterprise-license) cannot use safelisting with persisted queries. The feature relies on Apollo Uplink to fetch persisted query manifests, so it doesn't work as designed when the router is disconnected from Uplink. diff --git a/docs/source/configuration/subgraph-error-inclusion.mdx b/docs/source/configuration/subgraph-error-inclusion.mdx index a5a13c77ec..f56bcf92ba 100644 --- a/docs/source/configuration/subgraph-error-inclusion.mdx +++ b/docs/source/configuration/subgraph-error-inclusion.mdx @@ -1,10 +1,10 @@ --- title: Subgraph Error Inclusion subtitle: Configure the router to propagate subgraph errors to clients -description: Configure the Apollo Router to propagate subgraph errors to clients for all subgraphs or on a per-subgraph basis. +description: Configure the Apollo GraphOS Router or Apollo Router Core to propagate subgraph errors to clients for all subgraphs or on a per-subgraph basis. --- -By default, the Apollo Router redacts the details of subgraph errors in its responses to clients. The router instead returns a default error with the following message: +By default, a GraphOS Router or Apollo Router Core redacts the details of subgraph errors in responses to clients. The router instead returns a default error with the following message: ``` Subgraph errors redacted diff --git a/docs/source/configuration/telemetry/apollo-telemetry.mdx b/docs/source/configuration/telemetry/apollo-telemetry.mdx index 4094a20240..c5f6c0c609 100644 --- a/docs/source/configuration/telemetry/apollo-telemetry.mdx +++ b/docs/source/configuration/telemetry/apollo-telemetry.mdx @@ -1,14 +1,14 @@ --- title: GraphOS reporting -subtitle: Send Apollo Router operation metrics to GraphOS -description: Report GraphQL operation usage metrics from the Apollo Router to GraphOS to enable schema checks and metrics visualization in GraphOS Studio. +subtitle: Send router operation metrics to GraphOS +description: Report GraphQL operation usage metrics from the Apollo GraphOS Router to GraphOS to enable schema checks and metrics visualization in GraphOS Studio. --- -The Apollo Router can report operation usage metrics to [GraphOS](/graphos/) that you can then visualize in GraphOS Studio. These metrics also enable powerful GraphOS features like [schema checks](/graphos/delivery/schema-checks/). +The GraphOS Router and Apollo Router Core can report operation usage metrics to [GraphOS](/graphos/) that you can then visualize in GraphOS Studio. These metrics also enable powerful GraphOS features like [schema checks](/graphos/delivery/schema-checks/). ## Enabling usage reporting -You enable usage reporting in the Apollo Router by setting the following environment variables: +You enable usage reporting in the router by setting the following environment variables: ```bash export APOLLO_KEY= @@ -36,7 +36,7 @@ Your subgraph libraries must support federated tracing (also known as FTV1 traci ### Subgraph trace sampling -By default, the Apollo Router requests subgraph trace data from operations with a 1% sampling probability per operation. In most cases, this provides a sufficient sample size while minimizing latency for most operations (traces can affect latency because they increase the size of subgraph response payloads). +By default, the router requests subgraph trace data from operations with a 1% sampling probability per operation. In most cases, this provides a sufficient sample size while minimizing latency for most operations (traces can affect latency because they increase the size of subgraph response payloads). You can customize your router's trace sampling probability by setting the following options in your [YAML config file](./overview/#yaml-config-file): @@ -58,7 +58,7 @@ telemetry: -Because field-level instrumentation is dependent on general-purpose [OpenTelemetry tracing](./configuration/telemetry/exporters/tracing/overview), the value of `telemetry.apollo.field_level_instrumentation_sampler` cannot exceed the value of `telemetry.exporters.tracing.common.sampler`. +Because field-level instrumentation is dependent on general-purpose [OpenTelemetry tracing](./exporters/tracing/overview), the value of `telemetry.apollo.field_level_instrumentation_sampler` cannot exceed the value of `telemetry.exporters.tracing.common.sampler`. @@ -313,7 +313,7 @@ telemetry: ### `errors` -You can configure whether the Apollo Router reports GraphQL error information to GraphOS, and whether the details of those errors are redacted. You can customize this behavior globally and override that global behavior on a per-subgraph basis. +You can configure whether the router reports GraphQL error information to GraphOS, and whether the details of those errors are redacted. You can customize this behavior globally and override that global behavior on a per-subgraph basis. By default, your router _does_ report error information, and it _does_ redact the details of those errors. diff --git a/docs/source/configuration/telemetry/exporters/logging/overview.mdx b/docs/source/configuration/telemetry/exporters/logging/overview.mdx index c16b0f8eb9..216375d71e 100644 --- a/docs/source/configuration/telemetry/exporters/logging/overview.mdx +++ b/docs/source/configuration/telemetry/exporters/logging/overview.mdx @@ -1,16 +1,16 @@ --- title: Router Logging -subtitle: Configure logging in the Apollo Router -description: Configure logging in the Apollo Router. Set the log level and output format. +subtitle: Configure logging in the router +description: Configure logging in the Apollo GraphOS Router or Apollo Router Core. Set the log level and output format. --- -The Apollo Router provides built-in logging to capture records about the router's activity. +GraphOS Router and Apollo Router Core provide built-in logging to capture records about their activity. -The router supports [configurable log levels](#log-level) and [stdout output](./stdout) of log messages (with [configurable output formats](./stdout/#logging-output-format)). +The router supports [configurable log levels](#log-level) and [stdout output](./stdout) of log messages (with [configurable output formats](./stdout/#logging-output-format)). ## Log level -The Apollo Router accepts a command-line argument to set its log level: +The router accepts a command-line argument to set its log level: @@ -66,7 +66,7 @@ APOLLO_ROUTER_LOG=hyper=debug,info,h2=trace In both examples, the actual filter used by the router the value defined by `RUST_LOG`. -For more information about specifying filters for more granular control over Apollo Router logging, see the [Env Logger documentation](https://docs.rs/env_logger/latest/env_logger/). +For more information about specifying filters for more granular control over router logging, see the [Env Logger documentation](https://docs.rs/env_logger/latest/env_logger/). ## Logging common configuration diff --git a/docs/source/configuration/telemetry/exporters/logging/stdout.mdx b/docs/source/configuration/telemetry/exporters/logging/stdout.mdx index a96bf36bdd..36848ec241 100644 --- a/docs/source/configuration/telemetry/exporters/logging/stdout.mdx +++ b/docs/source/configuration/telemetry/exporters/logging/stdout.mdx @@ -1,10 +1,10 @@ --- title: Router Logging to stdout subtitle: Configure logging to stdout -description: Configure logging output to stdout in the Apollo Router. Format in human-readable text or machine-readable JSON. +description: Configure logging output to stdout in the Apollo GraphOS Router or Apollo Router Core. Format in human-readable text or machine-readable JSON. --- -You can configure Apollo Router logging to be directed to stdout, and its output format can be set to text or JSON. +You can configure GraphOS Router or Apollo Router Core logging to be directed to stdout, and its output format can be set to text or JSON. For general logging configuration, refer to [Router Logging Configuration](./overview). @@ -46,7 +46,7 @@ telemetry: You can configure the log format when you're running on an interactive shell. This is useful during development. -If both `format` and `tty_format` are configured then the output depends on the environment where the Router is run: +If both `format` and `tty_format` are configured then the output depends on the environment where the router is run: * In an interactive shell, `tty_format` will take precedence. * In a non-interactive shell, `format` will take precedence. diff --git a/docs/source/configuration/telemetry/exporters/metrics/datadog.mdx b/docs/source/configuration/telemetry/exporters/metrics/datadog.mdx index bcf4ddb6ea..5ec3ed40df 100644 --- a/docs/source/configuration/telemetry/exporters/metrics/datadog.mdx +++ b/docs/source/configuration/telemetry/exporters/metrics/datadog.mdx @@ -1,10 +1,10 @@ --- title: Datadog exporter (via OTLP) subtitle: Configure the Datadog exporter for metrics -description: Configure the Datadog exporter for metrics via OpenTelemetry Protocol (OTLP) in the Apollo Router. +description: Configure the Datadog exporter for metrics via OpenTelemetry Protocol (OTLP) in the Apollo GraphOS Router or Apollo Router Core. --- -Enable and configure the [OTLP exporter](./otlp) for metrics in the Apollo Router for use with [Datadog](https://www.datadoghq.com/). +Enable and configure the [OTLP exporter](./otlp) for metrics in the GraphOS Router or Apollo Router Core for use with [Datadog](https://www.datadoghq.com/). For general tracing configuration, refer to [Router Metrics Configuration](./overview). diff --git a/docs/source/configuration/telemetry/exporters/metrics/dynatrace.mdx b/docs/source/configuration/telemetry/exporters/metrics/dynatrace.mdx index 82ae53780a..41942dbb38 100644 --- a/docs/source/configuration/telemetry/exporters/metrics/dynatrace.mdx +++ b/docs/source/configuration/telemetry/exporters/metrics/dynatrace.mdx @@ -33,7 +33,7 @@ telemetry: -You must specify `protocol: http` or the exporter will fail to connect to Dynatrace. +You must specify `protocol: http` or the exporter will fail to connect to Dynatrace. Additionally, if your Dynatrace endpoint does not contain a port, you must append `:443` to the endpoint. For example: `https://subdomain.live.dynatrace.com:443/api/v2/otlp/v1/traces`. diff --git a/docs/source/configuration/telemetry/exporters/metrics/new-relic.mdx b/docs/source/configuration/telemetry/exporters/metrics/new-relic.mdx index 13402a1ed8..f7efa320b5 100644 --- a/docs/source/configuration/telemetry/exporters/metrics/new-relic.mdx +++ b/docs/source/configuration/telemetry/exporters/metrics/new-relic.mdx @@ -1,10 +1,10 @@ --- title: New Relic exporter (via OTLP) subtitle: Configure the New Relic exporter for metrics -description: Configure the New Relic exporter for metrics via OpenTelemetry Protocol (OTLP) in the Apollo Router. +description: Configure the New Relic exporter for metrics via OpenTelemetry Protocol (OTLP) in the Apollo GraphOS Router or Apollo Router Core. --- -Enable and configure the [OTLP exporter](./otlp) for metrics in the Apollo Router for use with [New Relic](https://newrelic.com/). +Enable and configure the [OTLP exporter](./otlp) for metrics in the GraphOS Router or Apollo Router Core for use with [New Relic](https://newrelic.com/). For general tracing configuration, refer to [Router Metrics Configuration](./overview). diff --git a/docs/source/configuration/telemetry/exporters/metrics/otlp.mdx b/docs/source/configuration/telemetry/exporters/metrics/otlp.mdx index 9bdcea173c..8699cfe5b4 100644 --- a/docs/source/configuration/telemetry/exporters/metrics/otlp.mdx +++ b/docs/source/configuration/telemetry/exporters/metrics/otlp.mdx @@ -1,12 +1,12 @@ --- title: OpenTelemetry Protocol (OTLP) exporter subtitle: Configure the OpenTelemetry Protocol (OTLP) exporter for metrics -description: Configure the OpenTelemetry Protocol (OTLP) exporter for metrics in the Apollo Router. +description: Configure the OpenTelemetry Protocol (OTLP) exporter for metrics in the Apollo GraphOS Router or Apollo Router Core. --- import BatchProcessorPreamble from '../../../../../shared/batch-processor-preamble.mdx'; import BatchProcessorRef from '../../../../../shared/batch-processor-ref.mdx'; -Enable and configure the [OpenTelemetry Protocol (OTLP)](https://www.opentelemetry.io/) exporter for metrics in the Apollo Router. +Enable and configure the [OpenTelemetry Protocol (OTLP)](https://www.opentelemetry.io/) exporter for metrics in the GraphOS Router or Apollo Router Core. For general metrics configuration, refer to [Router Metrics Configuration](./overview). @@ -18,7 +18,7 @@ Using the OTLP protocol, you can export metrics to any OTLP compatible receiver, ## OTLP configuration -The Apollo Router can be configured to export metrics data using OTLP over either HTTP or gRPC. +The router can be configured to export metrics data using OTLP over either HTTP or gRPC. An example router configuration using OTLP with gRPC: diff --git a/docs/source/configuration/telemetry/exporters/metrics/overview.mdx b/docs/source/configuration/telemetry/exporters/metrics/overview.mdx index 36f413c357..b8a2cb256f 100644 --- a/docs/source/configuration/telemetry/exporters/metrics/overview.mdx +++ b/docs/source/configuration/telemetry/exporters/metrics/overview.mdx @@ -1,10 +1,10 @@ --- title: Metrics exporters -subtitle: Export Apollo Router metrics -description: Collect and export metrics from the Apollo Router for Prometheus, OpenTelemetry Protocol (OTLP), Datadog, and New Relic. +subtitle: Export router metrics +description: Collect and export metrics from the Apollo GraphOS Router or Apollo Router Core for Prometheus, OpenTelemetry Protocol (OTLP), Datadog, and New Relic. --- -The Apollo Router supports collection of metrics with [OpenTelemetry](https://opentelemetry.io/), with exporters for: +The GraphOS Router and Apollo Router Core support collection of metrics with [OpenTelemetry](https://opentelemetry.io/), with exporters for: * [Prometheus](./prometheus) * [OpenTelemetry Protocol (OTLP)](./otlp) @@ -245,4 +245,4 @@ telemetry: ## Related topics * [Connecting OpenTelemetry traces to Prometheus](/technotes/TN0003-opentelemetry-traces-to-prometheus) -* [Sending Apollo Router traces and metrics to APM tools using OpenTelemetry](/technotes/TN0015-router-to-apm-via-opentelemetry/) +* [Sending router traces and metrics to APM tools using OpenTelemetry](/technotes/TN0015-router-to-apm-via-opentelemetry/) diff --git a/docs/source/configuration/telemetry/exporters/metrics/prometheus.mdx b/docs/source/configuration/telemetry/exporters/metrics/prometheus.mdx index f958931d14..185276a0b7 100644 --- a/docs/source/configuration/telemetry/exporters/metrics/prometheus.mdx +++ b/docs/source/configuration/telemetry/exporters/metrics/prometheus.mdx @@ -1,10 +1,10 @@ --- title: Prometheus exporter subtitle: Configure the Prometheus metrics exporter -description: Configure the Prometheus metrics exporter endpoint in the Apollo Router. +description: Configure the Prometheus metrics exporter endpoint in the Apollo GraphOS Router or Apollo Router Core. --- -Enable and configure the [Prometheus](https://www.prometheus.io/) exporter for metrics in the Apollo Router. +Enable and configure the [Prometheus](https://www.prometheus.io/) exporter for metrics in the GraphOS Router or Apollo Router Core. For general metrics configuration, refer to [Router Metrics Configuration](./overview). diff --git a/docs/source/configuration/telemetry/exporters/tracing/datadog.mdx b/docs/source/configuration/telemetry/exporters/tracing/datadog.mdx index 466e0accd1..0eea7691d9 100644 --- a/docs/source/configuration/telemetry/exporters/tracing/datadog.mdx +++ b/docs/source/configuration/telemetry/exporters/tracing/datadog.mdx @@ -1,12 +1,12 @@ --- title: Datadog exporter (via OTLP) subtitle: Configure the Datadog exporter for tracing -description: Configure the Datadog exporter for tracing via OpenTelemetry Protocol (OTLP) in the Apollo Router. +description: Configure the Datadog exporter for tracing via OpenTelemetry Protocol (OTLP) in the Apollo GraphOS Router or Apollo Router Core. --- import BatchProcessorPreamble from '../../../../../shared/batch-processor-preamble.mdx'; import BatchProcessorRef from '../../../../../shared/batch-processor-ref.mdx'; -Enable and configure the [Datadog](https://www.datadoghq.com/) exporter for tracing in the Apollo Router. +Enable and configure the [Datadog](https://www.datadoghq.com/) exporter for tracing in the GraphOS Router or Apollo Router Core. For general tracing configuration, refer to [Router Tracing Configuration](./overview). @@ -66,7 +66,7 @@ Native Datadog tracing is not part of the OpenTelemetry spec, and given that Dat -The Apollo Router can be configured to connect to either the native, default Datadog agent address or a URL: +The router can be configured to connect to either the native, default Datadog agent address or a URL: ```yaml title="router.yaml" telemetry: @@ -92,7 +92,7 @@ Set to true to enable the Datadog exporter. Defaults to false. ### `enable_span_mapping` (default: `true`) -[There are some incompatibilities](https://docs.rs/opentelemetry-datadog/latest/opentelemetry_datadog/#quirks) between Datadog and OpenTelemetry, the Datadog exporter might not provide meaningful contextual information in the exported spans. To fix this, you can configure the Apollo Router to perform a mapping for the span name and the span resource name. +[There are some incompatibilities](https://docs.rs/opentelemetry-datadog/latest/opentelemetry_datadog/#quirks) between Datadog and OpenTelemetry, the Datadog exporter might not provide meaningful contextual information in the exported spans. To fix this, you can configure the router to perform a mapping for the span name and the span resource name. ```yaml title="router.yaml" telemetry: @@ -103,14 +103,14 @@ telemetry: enable_span_mapping: true ``` -When `enable_span_mapping: true`, the Apollo Router will perform the following mapping: +With `enable_span_mapping: true`, the router performs the following mapping: 1. Use the OpenTelemetry span name to set the Datadog span operation name. 2. Use the OpenTelemetry span attributes to set the Datadog span resource name. #### Example trace -Let's say we send a query `MyQuery` to the Apollo Router, then the Router using the operation's query plan will send a query to `my-subgraph-name` and the following trace will be created: +For example, assume a client sends a query `MyQuery` to the router. The router's query planner sends a subgraph query to `my-subgraph-name` and creates the following trace: ``` | apollo_router request | diff --git a/docs/source/configuration/telemetry/exporters/tracing/dynatrace.mdx b/docs/source/configuration/telemetry/exporters/tracing/dynatrace.mdx index 36fd263a9a..2ba82a6358 100644 --- a/docs/source/configuration/telemetry/exporters/tracing/dynatrace.mdx +++ b/docs/source/configuration/telemetry/exporters/tracing/dynatrace.mdx @@ -33,7 +33,7 @@ telemetry: -You must specify `protocol: http` or the exporter will fail to connect to Dynatrace. +You must specify `protocol: http` or the exporter will fail to connect to Dynatrace. Additionally, if your Dynatrace endpoint does not contain a port, you must append `:443` to the endpoint. For example: `https://subdomain.live.dynatrace.com:443/api/v2/otlp/v1/traces`. diff --git a/docs/source/configuration/telemetry/exporters/tracing/jaeger.mdx b/docs/source/configuration/telemetry/exporters/tracing/jaeger.mdx index 12e5c17739..7c29456231 100644 --- a/docs/source/configuration/telemetry/exporters/tracing/jaeger.mdx +++ b/docs/source/configuration/telemetry/exporters/tracing/jaeger.mdx @@ -1,13 +1,13 @@ --- title: Jaeger exporter (via OTLP) subtitle: Configure the Jaeger exporter for tracing -description: Configure the Jaeger exporter for tracing via OpenTelemetry Protocol (OTLP) in the Apollo Router. +description: Configure the Jaeger exporter for tracing via OpenTelemetry Protocol (OTLP) in the Apollo GraphOS Router or Apollo Router Core. --- import BatchProcessorPreamble from '../../../../../shared/batch-processor-preamble.mdx'; import BatchProcessorRef from '../../../../../shared/batch-processor-ref.mdx'; -Enable and configure the [Jaeger exporter](https://www.jaegertracing.io/) for tracing in the Apollo Router. +Enable and configure the [Jaeger exporter](https://www.jaegertracing.io/) for tracing in the GraphOS Router or Apollo Router Core. For general tracing configuration, refer to [Router Tracing Configuration](./overview). @@ -44,11 +44,11 @@ See [OTLP configuration](./otlp#configuration) for more details on settings. -[Native Jaegar tracing is deprecated](https://opentelemetry.io/blog/2022/jaeger-native-otlp/) and will be removed in a future release of the Apollo Router. Use [Jaeger via OTLP](#jaeger-otlp-configuration) instead. +[Native Jaegar tracing is deprecated](https://opentelemetry.io/blog/2022/jaeger-native-otlp/) and will be removed in a future release of the router. Use [Jaeger via OTLP](#jaeger-otlp-configuration) instead. -The Apollo Router can be configured to export tracing data to Jaeger either via an agent or HTTP collector. +The router can be configured to export tracing data to Jaeger either via an agent or HTTP collector. Unless explicitly configured to use a collector, the router will use Jaeger agent by default. diff --git a/docs/source/configuration/telemetry/exporters/tracing/new-relic.mdx b/docs/source/configuration/telemetry/exporters/tracing/new-relic.mdx index a730e4f191..532816c1df 100644 --- a/docs/source/configuration/telemetry/exporters/tracing/new-relic.mdx +++ b/docs/source/configuration/telemetry/exporters/tracing/new-relic.mdx @@ -1,10 +1,10 @@ --- title: New Relic exporter (via OTLP) subtitle: Configure the New Relic exporter for tracing -description: Configure the New Relic exporter for tracing via OpenTelemetry Protocol (OTLP) in the Apollo Router. +description: Configure the New Relic exporter for tracing via OpenTelemetry Protocol (OTLP) in the Apollo GraphOS Router or Apollo Router Core. --- -Enable and configure the [OTLP exporter](./otlp) for tracing in the Apollo Router for use with [New Relic](https://newrelic.com/). +Enable and configure the [OTLP exporter](./otlp) for tracing in the GraphOS Router or Apollo Router Core for use with [New Relic](https://newrelic.com/). For general tracing configuration, refer to [Router Tracing Configuration](./overview). diff --git a/docs/source/configuration/telemetry/exporters/tracing/otlp.mdx b/docs/source/configuration/telemetry/exporters/tracing/otlp.mdx index e2dc4faf0d..dca5ea60c5 100644 --- a/docs/source/configuration/telemetry/exporters/tracing/otlp.mdx +++ b/docs/source/configuration/telemetry/exporters/tracing/otlp.mdx @@ -1,12 +1,12 @@ --- title: OpenTelemetry Protocol (OTLP) exporter subtitle: Configure the OpenTelemetry Protocol exporter for tracing -description: Configure the OpenTelemetry Protocol (OTLP) exporter for tracing in the Apollo Router. +description: Configure the OpenTelemetry Protocol (OTLP) exporter for tracing in the Apollo GraphOS Router or Apollo Router Core. --- import BatchProcessorPreamble from '../../../../../shared/batch-processor-preamble.mdx'; import BatchProcessorRef from '../../../../../shared/batch-processor-ref.mdx'; -Enable and configure the [OpenTelemetry Protocol (OTLP)](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md) exporter for tracing in the Apollo Router. +Enable and configure the [OpenTelemetry Protocol (OTLP)](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md) exporter for tracing in the GraphOS Router or Apollo Router Core. OTLP is the native protocol for OpenTelemetry. It can be used to export traces over HTTP or gRPC to a variety of backends including: @@ -19,7 +19,7 @@ For general tracing configuration, refer to [Router Tracing Configuration](./ove ## OTLP configuration -The Apollo Router can be configured to export tracing data using OTLP either via HTTP or gRPC: +The router can be configured to export tracing data using OTLP either via HTTP or gRPC: ```yaml title="router.yaml" telemetry: diff --git a/docs/source/configuration/telemetry/exporters/tracing/overview.mdx b/docs/source/configuration/telemetry/exporters/tracing/overview.mdx index 4ddbfaf5fc..1bab45a2c2 100644 --- a/docs/source/configuration/telemetry/exporters/tracing/overview.mdx +++ b/docs/source/configuration/telemetry/exporters/tracing/overview.mdx @@ -1,10 +1,10 @@ --- title: Router Tracing -subtitle: Collect tracing information from the Apollo Router -description: Collect and export tracing information from the Apollo Router. Supports OpenTelemetry Protocol (OTLP), Datadog, New Relic, Jaeger, Zipkin. +subtitle: Collect tracing information from the router +description: Collect and export tracing information from the Apollo GraphOS Router or Apollo Router Core. Supports OpenTelemetry Protocol (OTLP), Datadog, New Relic, Jaeger, Zipkin. --- -The Apollo Router supports collection of traces with [OpenTelemetry](https://opentelemetry.io/), with exporters for: +The GraphOS Router and Apollo Router Core support collection of traces with [OpenTelemetry](https://opentelemetry.io/), with exporters for: * [Jaeger](./jaeger) * [Zipkin](./zipkin) @@ -12,13 +12,13 @@ The Apollo Router supports collection of traces with [OpenTelemetry](https://ope * [New Relic](./new-relic) * [OpenTelemetry Protocol (OTLP)](./otlp) over HTTP or gRPC -The Apollo Router generates [**spans**](../../instrumentation/spans) that include the various phases of serving a request and associated dependencies. This is useful for showing how response time is affected by: +The router generates [**spans**](../../instrumentation/spans) that include the various phases of serving a request and associated dependencies. This is useful for showing how response time is affected by: * Sub-request response times * Query shape (sub-request dependencies) -* Apollo Router post-processing +* Router post-processing -Span data is sent to a collector such as [Jaeger](https://www.jaegertracing.io/), which can assemble spans into a gantt chart for analysis. +Span data is sent to a collector such as [Jaeger](https://www.jaegertracing.io/), which can assemble spans into a Gantt chart for analysis. @@ -227,4 +227,4 @@ Using this configuration you will have a response header called `my-trace-id` co ## Related topics * [Connecting OpenTelemetry traces to Prometheus](/technotes/TN0003-opentelemetry-traces-to-prometheus) -* [Sending Apollo Router traces and metrics to APM tools using OpenTelemetry](/technotes/TN0015-router-to-apm-via-opentelemetry/) +* [Sending router traces and metrics to APM tools using OpenTelemetry](/technotes/TN0015-router-to-apm-via-opentelemetry/) diff --git a/docs/source/configuration/telemetry/exporters/tracing/zipkin.mdx b/docs/source/configuration/telemetry/exporters/tracing/zipkin.mdx index f534c940a4..7b286af618 100644 --- a/docs/source/configuration/telemetry/exporters/tracing/zipkin.mdx +++ b/docs/source/configuration/telemetry/exporters/tracing/zipkin.mdx @@ -1,18 +1,18 @@ --- title: Zipkin exporter subtitle: Configure the Zipkin exporter for tracing -description: Enable and configure the Zipkin exporter for tracing in the Apollo Router. +description: Enable and configure the Zipkin exporter for tracing in the Apollo GraphOS Router or Apollo Router Core. --- import BatchProcessorPreamble from '../../../../../shared/batch-processor-preamble.mdx'; import BatchProcessorRef from '../../../../../shared/batch-processor-ref.mdx'; -Enable and configure the [Zipkin](https://zipkin.io/) exporter for tracing in the Apollo Router. +Enable and configure the [Zipkin](https://zipkin.io/) exporter for tracing in the GraphOS Router or Apollo Router Core. For general tracing configuration, refer to [Router Tracing Configuration](./overview). ## Zipkin configuration -The Apollo Router can be configured to export tracing data for Zipkin to either the default collector address or a URL: +The router can be configured to export tracing data for Zipkin to either the default collector address or a URL: ```yaml title="router.yaml" telemetry: diff --git a/docs/source/configuration/telemetry/instrumentation/conditions.mdx b/docs/source/configuration/telemetry/instrumentation/conditions.mdx index 778171c2b8..d67c75572e 100644 --- a/docs/source/configuration/telemetry/instrumentation/conditions.mdx +++ b/docs/source/configuration/telemetry/instrumentation/conditions.mdx @@ -1,7 +1,7 @@ --- title: Conditions subtitle: Set conditions for when events or instruments are triggered -description: Set conditions for when events or instruments are triggered in the Apollo Router. +description: Set conditions for when events or instruments are triggered in the Apollo GraphOS Router. --- You can set conditions for when an [instrument](./instruments) should be mutated or an [event](./events) should be triggered. diff --git a/docs/source/configuration/telemetry/instrumentation/events.mdx b/docs/source/configuration/telemetry/instrumentation/events.mdx index 1e75f17fb6..a4a3418f44 100644 --- a/docs/source/configuration/telemetry/instrumentation/events.mdx +++ b/docs/source/configuration/telemetry/instrumentation/events.mdx @@ -1,13 +1,13 @@ --- title: Events subtitle: Capture events from the router's request lifecycle -description: Capture standard and custom events from the Apollo Router's request lifecycle services. +description: Capture standard and custom events from the Apollo GraphOS Router's request lifecycle services. --- import RouterServices from '../../../../shared/router-lifecycle-services.mdx'; import TelemetryPerformanceNote from '../../../../shared/telemetry-performance.mdx'; -An _event_ is used to signal when something of note happens in the [Apollo Router's request lifecycle](../../../customizations/overview/#the-request-lifecycle). Events are output to both logs and traces. +An _event_ is used to signal when something of note happens in the [GraphOS Router's request lifecycle](../../../customizations/overview/#the-request-lifecycle). Events are output to both logs and traces. You can configure events for each service in `router.yaml`. Events can be standard or custom, and they can be triggered by configurable conditions. diff --git a/docs/source/configuration/telemetry/instrumentation/instruments.mdx b/docs/source/configuration/telemetry/instrumentation/instruments.mdx index 894969fac1..0e612a30a3 100644 --- a/docs/source/configuration/telemetry/instrumentation/instruments.mdx +++ b/docs/source/configuration/telemetry/instrumentation/instruments.mdx @@ -1,7 +1,7 @@ --- title: Instruments subtitle: Collect measurements with standard and custom instruments -description: Create and customize instruments to collect data and report measurements from the Apollo Router's request lifecycle services. +description: Create and customize instruments to collect data and report measurements from the Apollo GraphOS Router's request lifecycle services. --- import RouterServices from '../../../../shared/router-lifecycle-services.mdx'; @@ -63,7 +63,7 @@ telemetry: ### Apollo standard instruments -To learn about standard metric instruments for the router's request lifecycle, see [Apollo Router instruments](./standard-instruments). +To learn about Apollo-provided standard metric instruments for the router's request lifecycle, see [router instruments](./standard-instruments). ### Custom instruments diff --git a/docs/source/configuration/telemetry/instrumentation/selectors.mdx b/docs/source/configuration/telemetry/instrumentation/selectors.mdx index 55a4fdbbc6..59eaca160a 100644 --- a/docs/source/configuration/telemetry/instrumentation/selectors.mdx +++ b/docs/source/configuration/telemetry/instrumentation/selectors.mdx @@ -1,11 +1,11 @@ --- title: Selectors subtitle: Select data from the router pipeline to extract -description: Extract and select data from the Apollo Router's pipeline services to attach to telemetry. +description: Extract and select data from the Apollo GraphOS Router's pipeline services to attach to telemetry. --- import RouterServices from '../../../../shared/router-lifecycle-services.mdx'; -A _selector_ is used to extract data from the Apollo Router's request lifecycle (pipeline) services and attach them to telemetry, specifically [spans](./spans), [instruments](./instruments), [conditions](./conditions) and [events](./events). +A _selector_ is used to extract data from the GraphOS Router's request lifecycle (pipeline) services and attach them to telemetry, specifically [spans](./spans), [instruments](./instruments), [conditions](./conditions) and [events](./events). An example of a selector, `request_header`, of the router service on a custom span attribute: diff --git a/docs/source/configuration/telemetry/instrumentation/spans.mdx b/docs/source/configuration/telemetry/instrumentation/spans.mdx index 73553d1d61..120bbf58d1 100644 --- a/docs/source/configuration/telemetry/instrumentation/spans.mdx +++ b/docs/source/configuration/telemetry/instrumentation/spans.mdx @@ -1,7 +1,7 @@ --- title: Spans subtitle: Add router lifecycle context to traces -description: Use spans to add contextual information from the Apollo Router to traces displayed by your application performance monitors (APM). +description: Use spans to add contextual information from the Apollo GraphOS Router or Apollo Router Core to traces displayed by your application performance monitors (APM). --- import RouterServices from '../../../../shared/router-lifecycle-services.mdx'; @@ -33,7 +33,7 @@ telemetry: ### `attributes` -Spans may have attributes attached to them from the Apollo Router pipeline. These attributes are used to filter and group spans in your APM. +Spans may have attributes attached to them from the router pipeline. These attributes are used to filter and group spans in your APM. Attributes may be drawn from [standard attributes](./standard-attributes) or [selectors](./selectors). diff --git a/docs/source/configuration/telemetry/instrumentation/standard-attributes.mdx b/docs/source/configuration/telemetry/instrumentation/standard-attributes.mdx index b96bdcb877..4d71bedc64 100644 --- a/docs/source/configuration/telemetry/instrumentation/standard-attributes.mdx +++ b/docs/source/configuration/telemetry/instrumentation/standard-attributes.mdx @@ -1,7 +1,7 @@ --- title: OpenTelemetry standard attributes subtitle: Attach standard attributes to router telemetry -description: Attach OpenTelemetry (OTel) standard attributes to Apollo Router telemetry. +description: Attach OpenTelemetry (OTel) standard attributes to Apollo GraphOS Router or Apollo Router Core telemetry. --- import RouterServices from '../../../../shared/router-lifecycle-services.mdx'; diff --git a/docs/source/configuration/telemetry/instrumentation/standard-instruments.mdx b/docs/source/configuration/telemetry/instrumentation/standard-instruments.mdx index 8accb624a8..1a3358a38e 100644 --- a/docs/source/configuration/telemetry/instrumentation/standard-instruments.mdx +++ b/docs/source/configuration/telemetry/instrumentation/standard-instruments.mdx @@ -1,12 +1,12 @@ --- -title: Apollo Router instruments +title: Router Instruments subtitle: Standard metric instruments for the router's request lifecycle -description: Reference of standard metric instruments for the Apollo Router's request lifecycle. Consumable via the router's metrics exporters. +description: Reference of standard metric instruments for the request lifecycle of GraphOS Router and Apollo Router Core. Consumable via the router's metrics exporters. --- ## Standard metric instruments -The Apollo Router provides a set of non-configurable metric instruments that expose detailed information about the router's request lifecycle. +GraphOS Router and Apollo Router Core provide a set of non-configurable metric instruments that expose detailed information about the router's request lifecycle. These instruments can be consumed by configuring a [metrics exporter](../exporters/metrics/overview). @@ -109,7 +109,7 @@ The initial call to Uplink during router startup is not reflected in metrics. ### GraphOS Studio -- `apollo.router.telemetry.studio.reports` - The number of reports submitted to GraphOS Studio by the Router. +- `apollo.router.telemetry.studio.reports` - The number of reports submitted to GraphOS Studio by the router. - `report.type`: The type of report submitted: "traces" or "metrics" - `report.protocol`: Either "apollo" or "otlp", depending on the experimental_otlp_tracing_sampler configuration. diff --git a/docs/source/configuration/telemetry/overview.mdx b/docs/source/configuration/telemetry/overview.mdx index fe53b02b31..620e8480f3 100644 --- a/docs/source/configuration/telemetry/overview.mdx +++ b/docs/source/configuration/telemetry/overview.mdx @@ -1,19 +1,19 @@ --- -title: Apollo Router Telemetry +title: Router Telemetry subtitle: Collect observable data to monitor your router and supergraph -description: Observe and monitor the health and performance of GraphQL operations in the Apollo Router by collecting and exporting telemetry logs, metrics, and traces. +description: Observe and monitor the health and performance of GraphQL operations in the Apollo GraphOS Router or Apollo Router Core by collecting and exporting telemetry logs, metrics, and traces. --- import TelemetryPerformanceNote from '../../../shared/telemetry-performance.mdx'; In this overview, learn about: -- How Apollo Router telemetry enables supergraph observability and debuggability +- How GraphOS Router and Apollo Router Core telemetry enable supergraph observability and debuggability - What data is captured in the router's logs, metrics, and traces - What exporters are available to provide telemetry to your application performance monitoring (APM) tools ```mermaid flowchart LR - subgraph Apollo Router + subgraph Router lifecycle("Request Lifecycle
(telemetry sources)") exporters("Logs, Metrics,
Traces Exporters") lifecycle-->exporters @@ -30,7 +30,7 @@ The health of your supergraph is only as good as the health of your router. Beca Diagnosing your router's health and performance requires it to show observable data about its inner workings. The more observable data you can monitor and analyze, the faster you can identify unhealthy behaviors, deduce root causes, and implement fixes. -The Apollo Router provides the necessary data to monitor its health and troubleshoot issues. The router's observability is critical for maintaining a healthy, performant supergraph and minimizing its [mean time to repair (MTTR)](https://en.wikipedia.org/wiki/Mean_time_to_repair). +The router provides the necessary data to monitor its health and troubleshoot issues. The router's observability is critical for maintaining a healthy, performant supergraph and minimizing its [mean time to repair (MTTR)](https://en.wikipedia.org/wiki/Mean_time_to_repair). ## Collect exactly the telemetry you need @@ -42,7 +42,7 @@ Router telemetry is customizable to meet the observability needs of different gr ## Router telemetry types -The Apollo Router collects different types of telemetry, including: +The router collects different types of telemetry, including: * [Logs and events](#logs-and-events) * [Metrics and instruments](#metrics-and-instruments) @@ -52,7 +52,7 @@ These let you collect data about the inner workings of your router and export lo ```mermaid flowchart LR - subgraph Apollo Router + subgraph Router lifecycle("Request Lifecycle
(telemetry sources)") logs_exporter("Logs
Exporter") terminal(stdout) @@ -86,7 +86,7 @@ flowchart LR ### Logs and events -Logs record **events** in the Apollo Router. Examples of logged events include: +Logs record **events** in the router. Examples of logged events include: * Information about the router lifecycle * Warnings about misconfiguration @@ -110,7 +110,7 @@ See [Instruments](./instrumentation/instruments) for an overview of available in ### Traces and spans -Traces monitor the flow of a request through the Apollo Router. A trace is composed of [**spans**](./instrumentation/spans). A span captures a request's duration as it flows through the router request lifecycle. Spans may include contextual information about the request, such as the HTTP status code, or the name of the subgraph being queried. +Traces monitor the flow of a request through the router. A trace is composed of [**spans**](./instrumentation/spans). A span captures a request's duration as it flows through the router request lifecycle. Spans may include contextual information about the request, such as the HTTP status code, or the name of the subgraph being queried. Examples of spans include: @@ -122,7 +122,7 @@ Traces are consumed via [tracing exporters](./exporters/tracing/overview). ## Router telemetry exporters -The Apollo Router exports its collected telemetry in formats compatible with industry-standard APM tools. The router supports logging, metrics, and tracing exporters for a variety of tools, including: +The router exports its collected telemetry in formats compatible with industry-standard APM tools. The router supports logging, metrics, and tracing exporters for a variety of tools, including: * Prometheus * OpenTelemetry Collector @@ -135,7 +135,7 @@ For more information, see [logging exporters](./exporters/logging/overview), [me ## Router telemetry attributes -You can annotate events, metrics, and spans with **attributes**. Attributes are key-value pairs that add contextual information about the Apollo Router pipeline to telemetry. You can then use these attributes to filter and group data in your APMs. +You can annotate events, metrics, and spans with **attributes**. Attributes are key-value pairs that add contextual information about the router pipeline to telemetry. You can then use these attributes to filter and group data in your APMs. Example attributes include: diff --git a/docs/source/configuration/traffic-shaping.mdx b/docs/source/configuration/traffic-shaping.mdx index 2d60fde7fe..dfeb0cb5e1 100644 --- a/docs/source/configuration/traffic-shaping.mdx +++ b/docs/source/configuration/traffic-shaping.mdx @@ -1,11 +1,10 @@ --- -title: Traffic Shaping in the Apollo Router +title: Traffic Shaping subtitle: Tune the performance and reliability of traffic to and from the router -description: Fine-tune traffic performance and reliability in Apollo Router with YAML configuration for client and subgraph traffic shaping. +description: Fine-tune traffic performance and reliability in GraphOS Router and Apollo Router Core with YAML configuration for client and subgraph traffic shaping. --- -The Apollo Router provides various features to improve the performance and reliability of -the traffic between the client and router and between the router and subgraphs. +The GraphOS Router and Apollo Router Core provide various features to improve the performance and reliability of the traffic between the client and router and between the router and subgraphs. ## Configuration @@ -48,7 +47,7 @@ The preset values of `traffic_shaping` that's enabled by default: ### Rate limiting -The Apollo Router can apply rate limiting on client requests, as follows: +The router can apply rate limiting on client requests, as follows: ```yaml title="router.yaml" traffic_shaping: @@ -62,7 +61,7 @@ This rate limiting applies to all requests, there is no filtering per IP or othe ### Timeouts -The Apollo Router applies a default timeout of 30 seconds for all requests, including the following: +The router applies a default timeout of 30 seconds for all requests, including the following: - Requests the client makes to the router - Requests the router makes to subgraphs @@ -97,7 +96,7 @@ Compression is automatically supported on the client side, depending on the `Acc ### Query batching -The Apollo Router has _experimental_ support for receiving client query batches: +The router has support for receiving client query batches: ```yaml title="router.yaml" batching: @@ -109,7 +108,7 @@ For details, see [query batching for the router](../executing-operations/query-b ## Subgraph traffic shaping -The Apollo Router supports various options affecting traffic destined for subgraphs, that can either be defined for all subgraphs, or overriden per subgraph: +The router supports various options affecting traffic destined for subgraphs, that can either be defined for all subgraphs, or overriden per subgraph: ```yaml title="router.yaml" traffic_shaping: @@ -122,7 +121,7 @@ traffic_shaping: ### Compression -The Apollo Router can compress request bodies to subgraphs (along with response bodies to clients). +The router can compress request bodies to subgraphs (along with response bodies to clients). It currently supports these algorithms: `gzip`, `br`, and `deflate`. ```yaml title="router.yaml" @@ -169,13 +168,13 @@ traffic_shaping: ### Variable deduplication -When subgraphs are sent entity requests by the Router using the `_entities` field, it is often the case that the same entity (identified by a unique `@key` constraint) is requested multiple times within the execution of a single federated query. For example, an author's name might need to be fetched multiple times when accessing a list of a reviews for a product for which the author has written multiple reviews. +When subgraphs are sent entity requests by the router using the `_entities` field, it is often the case that the same entity (identified by a unique `@key` constraint) is requested multiple times within the execution of a single federated query. For example, an author's name might need to be fetched multiple times when accessing a list of a reviews for a product for which the author has written multiple reviews. To reduce the size of subgraph requests and the amount of work they might perform, the list of entities sent can be deduplicated. This is always active. ### Query deduplication -If the Router is simultaneously processing similar queries, it may result in producing multiple identical requests to a subgraph. With the `deduplicate_query` functionality enabled (by default, it is disabled), the Router can avoid sending the same query multiple times and instead buffer one or more of the dependent queries pending the result of the first, and reuse that result to fulfill all of the initial queries. This will reduce the overall traffic to the subgraph and the overall client request latency. To meet the criteria for deduplication, the feature must be enabled and the subgraph queries must have have the same HTTP path, headers and body: +If the router is simultaneously processing similar queries, it may result in producing multiple identical requests to a subgraph. With the `deduplicate_query` functionality enabled (by default, it is disabled), the router can avoid sending the same query multiple times and instead buffer one or more of the dependent queries pending the result of the first, and reuse that result to fulfill all of the initial queries. This will reduce the overall traffic to the subgraph and the overall client request latency. To meet the criteria for deduplication, the feature must be enabled and the subgraph queries must have have the same HTTP path, headers and body: ```yaml title="router.yaml" traffic_shaping: diff --git a/docs/source/containerization/docker.mdx b/docs/source/containerization/docker.mdx index f14037a4df..11aacdc11a 100644 --- a/docs/source/containerization/docker.mdx +++ b/docs/source/containerization/docker.mdx @@ -1,13 +1,12 @@ --- title: Run in Docker -subtitle: Run the Apollo Router container image in Docker -description: Run the Apollo Router container image in Docker with examples covering basic setup, configuration overrides, debugging, and building custom Docker images. +subtitle: Run the router container image in Docker +description: Run the Apollo Router Core container image in Docker with examples covering basic setup, configuration overrides, debugging, and building custom Docker images. --- -import { Link } from "gatsby"; import ElasticNotice from '../../shared/elastic-notice.mdx'; -This guide provides the following examples of running an Apollo Router container image in Docker: +This guide provides the following examples of running an Apollo Router Core container image in Docker: * Running a basic example with default configuration. * Customizing your configuration to override the default configuration. @@ -37,7 +36,7 @@ docker run -p 4000:4000 \ This command downloads your supergraph schema from Apollo and uses a default configuration that listens for connections on port `4000`. -For more complex configurations, such as overriding subgraph URLs or propagating headers, see [Configuring the Apollo Router](../configuration/overview/). +For more complex configurations, such as overriding subgraph URLs or propagating headers, see [Router Configuration](../configuration/overview/). ## Override the configuration diff --git a/docs/source/containerization/kubernetes.mdx b/docs/source/containerization/kubernetes.mdx index 78e3275380..a2393c5225 100644 --- a/docs/source/containerization/kubernetes.mdx +++ b/docs/source/containerization/kubernetes.mdx @@ -1,24 +1,23 @@ --- title: Deploy in Kubernetes -subtitle: Self-hosted deployment of Apollo Router in Kubernetes -description: Deploy the Apollo Router in Kubernetes using Helm charts. Customize configurations, enable metrics, and choose values for migration. +subtitle: Self-hosted deployment of the router in Kubernetes +description: Deploy the Apollo GraphOS Router or Apollo Router Core in Kubernetes using Helm charts. Customize configurations, enable metrics, and choose values for migration. --- -import { Link } from 'gatsby'; import ElasticNotice from '../../shared/elastic-notice.mdx'; import HelmShowOutput from '../../shared/helm-show-router-output.mdx'; import CoprocTypicalConfig from '../../shared/coproc-typical-config.mdx'; -Learn how to deploy a self-hosted Apollo Router in Kubernetes using Helm charts. +Learn how to deploy a self-hosted router (GraphOS Router or Apollo Router Core) in Kubernetes using Helm charts. ```mermaid flowchart LR; clients(Clients); subgraph "Kubernetes cluster"; lb(["Load Balancer"]) - router_a(["Apollo Router"]); + router_a(["Router"]); coproc_a(["Coprocessor"]); - router_b(["Apollo Router"]); + router_b(["Router"]); coproc_b(["Coprocessor"]); router_a <-.-> coproc_a; router_b <-.-> coproc_b; @@ -39,7 +38,7 @@ The following guides provide the steps to: ## About the router Helm chart -[Helm](https://helm.sh) is a package manager for Kubernetes (k8s). Apollo provides an application Helm chart with each release of Apollo Router in GitHub. Since the router version 0.14.0, Apollo has released the router Helm chart as an [Open Container Initiative (OCI)](https://helm.sh/docs/topics/registries/) image in our GitHub container registry. +[Helm](https://helm.sh) is a package manager for Kubernetes (k8s). Apollo provides an application Helm chart with each release of Apollo Router Core in GitHub. Since the router version 0.14.0, Apollo has released the router Helm chart as an [Open Container Initiative (OCI)](https://helm.sh/docs/topics/registries/) image in a GitHub container registry. @@ -51,7 +50,7 @@ You customize a deployed router with the same [command-line options and YAML con ## Basic deployment -Follow this guide to deploy the Apollo Router using Helm to install the basic chart provided with each router release. +Follow this guide to deploy the Router using Helm to install the basic chart provided with each router release. Each router chart has a `values.yaml` file with router and deployment settings. The released, unedited file has a few explicit settings, including: @@ -61,7 +60,7 @@ Each router chart has a `values.yaml` file with router and deployment settings. -The values of the Helm chart for Apollo Router v1.31.0 in the GitHub container repository, as output by the `helm show` command: +The values of the Helm chart for Apollo Router Core v1.31.0 in the GitHub container repository, as output by the `helm show` command: ```bash helm show values oci://ghcr.io/apollographql/helm-charts/router @@ -73,7 +72,7 @@ helm show values oci://ghcr.io/apollographql/helm-charts/router ### Set up Helm -1. Install [Helm](https://helm.sh/docs/intro/install/) **version 3.x**. The Apollo Router's Helm chart requires Helm v3.x. +1. Install [Helm](https://helm.sh/docs/intro/install/) **version 3.x**. The router's Helm chart requires Helm v3.x. @@ -107,7 +106,7 @@ For an example, see the [Setup from Apollo's Reference Architecture](https://git To manage the system resources you need to deploy the router on Kubernetes: -* Read [Managing Apollo Router resources in Kubernetes](/technotes/TN0016-router-resource-management/). +* Read [Managing router resources in Kubernetes](/technotes/TN0016-router-resource-management/). * Use the [router resource estimator](/technotes/TN0045-router_resource_estimator/). @@ -249,7 +248,7 @@ This is not specifically a router issue and Istio has instructions on how to man ## Configure for migration from gateway -When [migrating from `@apollo/gateway` to the Apollo Router](../migrating-from-gateway), consider the following tips to maximize the compatibility of your router deployment. +When [migrating from `@apollo/gateway` to the router](../migrating-from-gateway), consider the following tips to maximize the compatibility of your router deployment. ### Increase maximum request bytes diff --git a/docs/source/containerization/overview.mdx b/docs/source/containerization/overview.mdx index 1dd649fa7d..44c2302952 100644 --- a/docs/source/containerization/overview.mdx +++ b/docs/source/containerization/overview.mdx @@ -1,20 +1,20 @@ --- -title: Containerizing the Apollo Router -subtitle: Run Apollo Router images in containers -description: Containerize the Apollo Router for portability and scalability. Choose from default or debug images. Deploy in Kubernetes or run in Docker. +title: Containerizing the GraphOS Router +subtitle: Run router images in containers +description: Containerize the Apollo GraphOS Router for portability and scalability. Choose from default or debug images. Deploy in Kubernetes or run in Docker. --- import ElasticNotice from '../../shared/elastic-notice.mdx'; -Apollo provides container images of the Apollo Router. By containerizing the router, you can run it in a cluster and leverage the portability, scalability, and high availability benefits of containerization. Containers can also simplify and speed up local development. +Apollo provides container images of the Apollo Router Core that you can self-host and run with GraphOS as GraphOS Routers. By containerizing the router, you can run it in a cluster and leverage the portability, scalability, and high availability benefits of containerization. Containers can also simplify and speed up local development. -## About the Apollo Router container image +## About router container images -Apollo provides container images of the Apollo Router [on GitHub](https://github.com/apollographql/router/pkgs/container/router) in its container repository. The router images are based on [debian:bullseye-slim](https://hub.docker.com/_/debian/), which is designed to provide constrained, secure, and small images. +Apollo provides container images of the router [on GitHub](https://github.com/apollographql/router/pkgs/container/router) in its container repository. The router images are based on [debian:bullseye-slim](https://hub.docker.com/_/debian/), which is designed to provide constrained, secure, and small images. -Each release of the Apollo Router includes both default (production) and debug images. While each image for a release contains the same build, the debug images have helpful debugging utilities installed and run the router under the control of [heaptrack](https://github.com/KDE/heaptrack). +Each release of the router includes both default (production) and debug images. While each image for a release contains the same build, the debug images have helpful debugging utilities installed and run the router under the control of [heaptrack](https://github.com/KDE/heaptrack). A router image has the following layout: diff --git a/docs/source/customizations/coprocessor.mdx b/docs/source/customizations/coprocessor.mdx index 96303f2486..935468ce9c 100644 --- a/docs/source/customizations/coprocessor.mdx +++ b/docs/source/customizations/coprocessor.mdx @@ -1,14 +1,14 @@ --- -title: External Coprocessing in the Apollo Router +title: External Coprocessing subtitle: Customize your router's behavior in any language -description: Customize the Apollo Router with external coprocessing. Write standalone code in any language, hook into request lifecycle, and modify request/response details. +description: Customize the Apollo GraphOS Router with external coprocessing. Write standalone code in any language, hook into request lifecycle, and modify request/response details. --- import CoprocTypicalConfig from '../../shared/coproc-typical-config.mdx'; -With **external coprocessing**, you can hook into the Apollo Router's request-handling lifecycle by writing standalone code in any language and framework. This code (i.e., your **coprocessor**) can run anywhere on your network that's accessible to the router over HTTP. +With **external coprocessing**, you can hook into the GraphOS Router's request-handling lifecycle by writing standalone code in any language and framework. This code (i.e., your **coprocessor**) can run anywhere on your network that's accessible to the router over HTTP. You can configure your router to "call out" to your coprocessor at different **stages** throughout the request-handling lifecycle, enabling you to perform custom logic based on a client request's headers, query string, and other details. This logic can access disk and perform network requests, all while safely isolated from the critical router process. @@ -1119,7 +1119,7 @@ If you return a successful response, make sure the structure of the `data` prope ### Failed responses -If a request to a coprocessor results in a **failed response**, which is seperate from a **control break**, the Router will return an error to the client making the supergraph request. The router considers all of the following scenarios to be a **failed response** from your coprocessor: +If a request to a coprocessor results in a **failed response**, which is seperate from a **control break**, the router will return an error to the client making the supergraph request. The router considers all of the following scenarios to be a **failed response** from your coprocessor: - Your coprocessor doesn't respond within the amount of time specified by the `timeout` key in your [configuration](#typical-configuration) (default one second). - Your coprocessor responds with a non-`2xx` HTTP code. @@ -1129,7 +1129,7 @@ If a request to a coprocessor results in a **failed response**, which is seperat ## Handling deferred query responses -The Apollo Router supports the incremental delivery of query response data via [the `@defer` directive](../executing-operations/defer-support/): +GraphOS Router and Apollo Router Core support the incremental delivery of query response data via [the `@defer` directive](../executing-operations/defer-support/): ```mermaid sequenceDiagram diff --git a/docs/source/customizations/custom-binary.mdx b/docs/source/customizations/custom-binary.mdx index 4af39b9281..c2a6933146 100644 --- a/docs/source/customizations/custom-binary.mdx +++ b/docs/source/customizations/custom-binary.mdx @@ -1,13 +1,13 @@ --- -title: Creating a Custom Apollo Router Binary +title: Creating a Custom Apollo Router Core Binary subtitle: Compile a custom router binary from source -description: Compile a custom Apollo Router binary from source. Learn to create native Rust plugins. +description: Compile a custom Apollo Router Core binary from source. Learn to create native Rust plugins. --- import ElasticNotice from '../../shared/elastic-notice.mdx'; import NativePluginNotice from '../../shared/native-plugin-notice.mdx'; -Learn how to compile a custom Apollo Router binary from source, which is required to create custom native Rust plugins for the router. +Learn how to compile a custom binary from Apollo Router Core source, which is required to create custom native Rust plugins for the router. @@ -15,7 +15,7 @@ Learn how to compile a custom Apollo Router binary from source, which is require ## Prerequisites -To compile the Apollo Router, you need to have the following installed: +To compile the router, you need to have the following installed: * [Rust 1.76.0 or later](https://www.rust-lang.org/tools/install) @@ -62,11 +62,11 @@ starstuff └── main.rs ``` -The Apollo Router uses an auto-discovery mechanism for plugins, so any plugins you add via dependency are automatically available to the Router at runtime. +The router uses an auto-discovery mechanism for plugins, so any plugins you add via dependency are automatically available to the router at runtime. ## 2. Compile the router -Create a debug build of the Apollo Router with the following command: +Create a debug build of the router with the following command: ```bash cargo build @@ -211,4 +211,4 @@ ENTRYPOINT ["/dist/router", "-s", "/dist/supergraph.graphql"] ## Related topics -* [Optimizing Custom Apollo Router Builds](/technotes/TN0030-optimizing-router-builds/) +* [Optimizing Custom Router Builds](/technotes/TN0030-optimizing-router-builds/) diff --git a/docs/source/customizations/native.mdx b/docs/source/customizations/native.mdx index 98ebacf53b..650dddcc58 100644 --- a/docs/source/customizations/native.mdx +++ b/docs/source/customizations/native.mdx @@ -1,19 +1,19 @@ --- -title: Writing Native Rust Plugins for the Apollo Router -subtitle: Extend the Apollo Router with custom Rust code -description: Extend the Apollo Router with custom Rust code. Plan, build, and register plugins. Define plugin configuration and implement lifecycle hooks. +title: Writing Native Rust Plugins +subtitle: Extend the router with custom Rust code +description: Extend the Apollo GraphOS Router or Apollo Router Core with custom Rust code. Plan, build, and register plugins. Define plugin configuration and implement lifecycle hooks. --- import ElasticNotice from '../../shared/elastic-notice.mdx'; import NativePluginNotice from '../../shared/native-plugin-notice.mdx'; -Your federated graph might have specific requirements that aren't supported by the Apollo Router's built-in [configuration options](../configuration/overview/). For example, you might need to further customize the behavior of: +Your federated graph might have specific requirements that aren't supported by the built-in [configuration options](../configuration/overview/) of the GraphOS Router or Apollo Router Core. For example, you might need to further customize the behavior of: * Authentication/authorization * Logging * Operation tracing -In these cases, you can create custom plugins for the Apollo Router. +In these cases, you can create custom plugins for the router. @@ -21,13 +21,13 @@ In these cases, you can create custom plugins for the Apollo Router. ## Planning a plugin -When designing a new plugin, you first want to determine which of the Apollo Router's **services** the plugin should hook into to achieve its use case. +When designing a new plugin, you first want to determine which of the router's **services** the plugin should hook into to achieve its use case. For descriptions of these services, see [Router request lifecycle](./rhai#router-request-lifecycle). ## Building a plugin -To demonstrate building a plugin, we'll walk through the [hello world example plugin](https://github.com/apollographql/router/tree/main/examples/hello-world) in the Router repo. +To demonstrate building a plugin, we'll walk through the [hello world example plugin](https://github.com/apollographql/router/tree/main/examples/hello-world) in the router repo. ### 1. Add modules @@ -70,7 +70,7 @@ impl Plugin for HelloWorld { ### 3. Implement the `Plugin` trait -All router plugins must implement the `Plugin` trait. This trait defines lifecycle hooks that enable hooking into Apollo Router services. +All router plugins must implement the `Plugin` trait. This trait defines lifecycle hooks that enable hooking into a router's services. The trait also provides a default implementations for each hook, which returns the associated service unmodified. @@ -155,7 +155,7 @@ fn supergraph_service( } ``` -The [tower-rs](https://github.com/tower-rs) library (which the Apollo Router is built on) comes with many "off-the-shelf" layers. In addition, Apollo provides layers that cover common functionality and integration with third-party products. +The [tower-rs](https://github.com/tower-rs) library (which the router is built on) comes with many "off-the-shelf" layers. In addition, Apollo provides layers that cover common functionality and integration with third-party products. Some notable layers are: * **buffered** - Make a service `Clone`. Typically required for any `async` layers. @@ -175,7 +175,7 @@ Sometimes you might need to pass custom information between services. For exampl * Authentication information obtained by the `SupergraphService` might be required by `SubgraphService`s. * Cache control headers from `SubgraphService`s might be aggregated and returned to the client by the `SupergraphService`. -Whenever the Apollo Router receives a request, it creates a corresponding `context` object and passes it along to each service. This object can store anything that's Serde-compatible (e.g., all simple types or a custom type). +Whenever the router receives a request, it creates a corresponding `context` object and passes it along to each service. This object can store anything that's Serde-compatible (e.g., all simple types or a custom type). All of your plugin's hooks can interact with the `context` object using the following functions: @@ -215,11 +215,11 @@ http_client.request().await; drop(_guard); ``` -The Router measures how much time it spends working on a request, by subtracting the time spent waiting on network calls, like subgraphs or coprocessors. The result is reported in the `apollo_router_processing_time` metric. If the native plugin is performing network calls, then they should be taken into account in this metric. It is done by calling the `enter_active_request` method, which returns a guard value. Until that value is dropped, the Router will consider that a network request is happening. +The Router measures how much time it spends working on a request, by subtracting the time spent waiting on network calls, like subgraphs or coprocessors. The result is reported in the `apollo_router_processing_time` metric. If the native plugin is performing network calls, then they should be taken into account in this metric. It is done by calling the `enter_active_request` method, which returns a guard value. Until that value is dropped, the router will consider that a network request is happening. ### 6. Register your plugin -To enable the Apollo Router to discover your plugin, you need to **register** the plugin. +To enable the router to discover your plugin, you need to **register** the plugin. To do so, use the `register_plugin!()` macro provided by `apollo-router`. This takes 3 arguments: @@ -251,7 +251,7 @@ To create custom metrics, traces, and spans, you can use [`tracing` macros](http ### Add custom metrics -Make sure to [enable prometheus metrics](../configuration/telemetry/exporters/metrics/prometheus) in your configuration if you want to have metrics generated by the Router. +Make sure to [enable Prometheus metrics](../configuration/telemetry/exporters/metrics/prometheus) in your configuration if you want to have metrics generated by the router. @@ -310,7 +310,7 @@ info_span!("my_span"); ## Plugin Lifecycle -Like individual requests, plugins follow their own strict lifecycle that helps provide structure to the Apollo Router's execution. +Like individual requests, plugins follow their own strict lifecycle that helps provide structure to the router's execution. ### Creation diff --git a/docs/source/customizations/overview.mdx b/docs/source/customizations/overview.mdx index a8ead13ec4..74a318dbc7 100644 --- a/docs/source/customizations/overview.mdx +++ b/docs/source/customizations/overview.mdx @@ -1,14 +1,14 @@ --- -title: Apollo Router Customizations +title: Router Customizations subtitle: Extend your router with custom functionality -description: Extend the Apollo Router with custom functionality. Understand the request lifecycle and how customizations intervene at specific points. +description: Extend the GraphOS Router or Apollo Router Core with custom functionality. Understand the request lifecycle and how customizations intervene at specific points. --- -You can create **customizations** for the Apollo Router to add functionality that isn't available via built-in [configuration options](../configuration/overview/). For example, you can make an external call to fetch authentication data for each incoming request. +You can create **customizations** for the GraphOS Router or Apollo Router Core to add functionality that isn't available via built-in [configuration options](../configuration/overview/). For example, you can make an external call to fetch authentication data for each incoming request. ## Customization types -The Apollo Router supports the following customization types: +The GraphOS Router supports the following customization types: - [**Rhai scripts**](./rhai/) - The [Rhai scripting language](https://rhai.rs/book/) lets you add functionality directly to your stock router binary by hooking into different phases of the router's request lifecycle. @@ -16,6 +16,8 @@ The Apollo Router supports the following customization types: - If your organization has a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/), you can write custom request-handling code in any language. This code can run in the same container as your router or separately. - The router calls your custom code via HTTP, passing it the details of each incoming client request. +The Apollo Router Core supports customization only through [Rhai scripts](./rhai/). + Because [Rhai scripts](./rhai/) are easier to deploy, we recommend using them if they support your use case. Use external co-processing if your customization needs to do any of the following (which Rhai scripts _don't_ support): - Read or write to disk @@ -31,7 +33,7 @@ flowchart RL subgraph client["Client"] end - subgraph router["Apollo Router"] + subgraph router["Router"] direction LR routerService("Router
Service") supergraphService("Supergraph
Service") @@ -84,7 +86,7 @@ NextService["Next service"] -->|response| coreService Each request and response object contains a `Context` object, which is carried throughout the entire process. Each request's `Context` object is unique. You can use it to store plugin-specific information between the request and response or to communicate between different hook points. (A plugin can be called at multiple steps of the request lifecycle.) The following flowcharts diagram the entire request lifecycle. -The first details the path of a request from a client, through the parts of the Apollo Router, all the way to your subgraphs. +The first details the path of a request from a client, through the parts of the router, all the way to your subgraphs. The second details the path of a response from your subgraphs back to the client. ### Request path @@ -92,7 +94,7 @@ The second details the path of a response from your subgraphs back to the client ```mermaid flowchart TB; client(Client); - subgraph router["Apollo Router"] + subgraph router["Router"] direction LR httpServer("HTTP server") subgraph routerService["Router Service"] diff --git a/docs/source/customizations/rhai-api.mdx b/docs/source/customizations/rhai-api.mdx index 0279e678d1..c4e4a316f6 100644 --- a/docs/source/customizations/rhai-api.mdx +++ b/docs/source/customizations/rhai-api.mdx @@ -1,14 +1,14 @@ --- title: Rhai Script API Reference -subtitle: For Apollo Router customizations -description: This reference documents the symbols and behaviors that are specific to Rhai customizations for the Apollo Router. Includes entry point hooks, logging, and more. +subtitle: APIs for router customizations +description: This reference documents the symbols and behaviors that are specific to Rhai customizations for the Apollo GraphOS Router and Apollo Router Core. Includes entry point hooks, logging, and more. --- -This reference documents the symbols and behaviors that are specific to [Rhai customizations](./rhai/) for the Apollo Router. +This reference documents the symbols and behaviors that are specific to [Rhai customizations](./rhai/) for the GraphOS Router and Apollo Router Core. ## Entry point hooks -Your Rhai script's [main file](./rhai/#the-main-file) hooks into the individual services of the Apollo Router's [request-handling lifecycle](./rhai/#router-request-lifecycle). To do so, it defines whichever combination of the following entry point hooks it requires: +Your Rhai script's [main file](./rhai/#the-main-file) hooks into the individual services of the router's [request-handling lifecycle](./rhai/#router-request-lifecycle). To do so, it defines whichever combination of the following entry point hooks it requires: ```rhai fn router_service(service) {} @@ -36,7 +36,7 @@ fn supergraph_service(service) { ## Logging -If your script logs a message with Rhai's built-in `print()` function, it's logged to the Apollo Router's logs at the "info" level: +If your script logs a message with Rhai's built-in `print()` function, it's logged to the router's logs at the "info" level: ```rhai print("logged at the info level"); diff --git a/docs/source/customizations/rhai.mdx b/docs/source/customizations/rhai.mdx index 710f4171a5..6bad60dfe0 100644 --- a/docs/source/customizations/rhai.mdx +++ b/docs/source/customizations/rhai.mdx @@ -1,10 +1,10 @@ --- -title: Rhai Scripts for the Apollo Router +title: Rhai Scripts to customize routers subtitle: Add custom functionality directly to your router -description: Customize Apollo Router functionality with Rhai scripts. Manipulate strings, process headers and more for enhanced performance. +description: Customize your Apollo Router Core or GraphOS Router functionality with Rhai scripts. Manipulate strings, process headers and more for enhanced performance. --- -You can customize the Apollo Router's behavior with scripts that use the [Rhai scripting language](https://rhai.rs/book/). In a Rust-based project, Rhai is ideal for performing common scripting tasks such as manipulating strings and processing headers. Your Rhai scripts can also hook into multiple stages of the router's [request handling lifecycle](#router-request-lifecycle). +You can customize your GraphOS Router or Apollo Router Core's behavior with scripts that use the [Rhai scripting language](https://rhai.rs/book/). In a Rust-based project, Rhai is ideal for performing common scripting tasks such as manipulating strings and processing headers. Your Rhai scripts can also hook into multiple stages of the router's [request handling lifecycle](#router-request-lifecycle). ## Rhai language reference @@ -12,7 +12,7 @@ To learn about Rhai, see the [Rhai language reference](https://rhai.rs/book/lang ## Use cases -Common use cases for Rhai scripts in Apollo Router include: +Common use cases for Rhai scripts in routers include: * Modifying the details of HTTP requests and responses. This includes requests sent from clients to your router, along with requests sent from your router to your subgraphs. You can modify any combination of the following: * Request and response bodies @@ -42,11 +42,11 @@ rhai: 1. Add the `rhai` top-level key to your router's [YAML config file](../configuration/overview/#yaml-config-file). * This key **must** contain at least one of a `scripts` key or a `main` key (see the example above). 2. Place all of your Rhai script files in a specific directory. - * By default, the Apollo Router looks in the `./rhai` directory (relative to the directory the `router` command is executed from). + * By default, the router looks in the `./rhai` directory (relative to the directory the `router` command is executed from). * You can override this default with the `scripts` key (see above). 3. Define a ["main" Rhai file](#the-main-file) in your router project. - * This file defines all of the "entry point" hooks that the Apollo Router uses to call into your script. - * By default, the Apollo Router looks for `main.rhai` in your Rhai script directory. + * This file defines all of the "entry point" hooks that the router uses to call into your script. + * By default, the router looks for `main.rhai` in your Rhai script directory. * You can override this default with the `main` key (see above). ## The main file @@ -102,7 +102,7 @@ fn subgraph_service(service, subgraph) { -You can provide _exactly one_ main Rhai file to the Apollo Router. This means that all of your customization's functionality must originate from these hook definitions. +You can provide _exactly one_ main Rhai file to the router. This means that all of your customization's functionality must originate from these hook definitions. To organize unrelated functionality within your Rhai customization, your main file can import and use symbols from any number of _other_ Rhai files (known as **modules**) in your script directory: @@ -138,7 +138,7 @@ fn supergraph_service(service) { ## Router request lifecycle -Before you build your Rhai script, it helps to understand how the Apollo Router handles each incoming GraphQL request. During each request's execution, different **services** in the router communicate with each other as shown: +Before you build your Rhai script, it helps to understand how the router handles each incoming GraphQL request. During each request's execution, different **services** in the router communicate with each other as shown: ```mermaid sequenceDiagram @@ -168,11 +168,11 @@ sequenceDiagram As execution proceeds "left to right" from the `RouterService` to individual `SubgraphService`s, each service passes the client's original request along to the _next_ service. Similarly, as execution continues "right to left" from `SubgraphService`s to the `RouterService`, each service passes the generated response for the client. -Your Rhai scripts can hook into any combination of the above services (if you are using the Apollo Router v1.30.0 and later). The scripts can modify the request, response, and/or related metadata as they're passed along. +Your Rhai scripts can hook into any combination of the above services (if you are using the Apollo Router Core v1.30.0 and later). The scripts can modify the request, response, and/or related metadata as they're passed along. ### Service descriptions -Each Apollo Router service has a corresponding function that a Rhai script can define to hook into that service: +Each service of the router has a corresponding function that a Rhai script can define to hook into that service:
@@ -242,7 +242,7 @@ Define `execution_service` if your customization includes logic to govern execut - + @@ -286,11 +286,11 @@ Custom clients can be implemented following the [spec documentation](https://git Without additional security, HTTP multipart requests can be exploited as part of [cross-site request forgery](https://owasp.org/www-community/attacks/csrf) (CSRF) attacks. -The Apollo Router already has a mechanism to prevent these types of attacks, which is enabled by default. You should verify that your router hasn't disabled this mechanism before using file uploads. See [Cross-Site Request Forgery Prevention](../configuration/csrf) for details. +The GraphOS Router already has a mechanism to prevent these types of attacks, which is enabled by default. You should verify that your router hasn't disabled this mechanism before using file uploads. See [Cross-Site Request Forgery Prevention](../configuration/csrf) for details. ## Metrics for file uploads -Metrics in the Apollo Router for file uploads: +Metrics in the GraphOS Router for file uploads:
-Handles communication between the Apollo Router and your subgraphs. +Handles communication between the router and your subgraphs. Define `subgraph_service` to configure this communication (for example, to dynamically add HTTP headers to pass to a subgraph). @@ -271,7 +271,7 @@ Each hook in your Rhai script's [main file](#main-file) is passed a `service` ob graph LR; client(Client); client --> router(router_service); - subgraph Apollo Router + subgraph Router router --> supergraph(supergraph_service); supergraph --> execution(execution_service); execution --> subs_a(subgraph_service); @@ -293,7 +293,7 @@ Each hook in your Rhai script's [main file](#main-file) is passed a `service` ob ```mermaid graph RL; client(Client); - subgraph Apollo Router + subgraph Router execution(execution_service); supergraph(supergraph_service); router(router_service); @@ -320,7 +320,7 @@ Each hook in your Rhai script's [main file](#main-file) is passed a `service` ob ## Example scripts -In addition to the examples below, see more examples in the Router repo's [examples directory](https://github.com/apollographql/router/tree/main/examples). Rhai-specific examples are listed in `README.md`. +In addition to the examples below, see more examples in the router repo's [examples directory](https://github.com/apollographql/router/tree/main/examples). Rhai-specific examples are listed in `README.md`. ### Handling incoming requests @@ -525,7 +525,7 @@ fn process_request(request) { ### Avoiding deadlocks -The Apollo Router requires that its Rhai engine implements the [sync feature](https://rhai.rs/book/start/features.html) to guarantee data integrity within the router's multi-threading execution environment. This means that [shared values](https://rhai.rs/book/language/fn-closure.html?highlight=deadlock#data-races-in-sync-builds-can-become-deadlocks) within Rhai might cause a deadlock. +The router requires its Rhai engine to implement the [sync feature](https://rhai.rs/book/start/features.html) to guarantee data integrity within the router's multi-threading execution environment. This means that [shared values](https://rhai.rs/book/language/fn-closure.html?highlight=deadlock#data-races-in-sync-builds-can-become-deadlocks) within Rhai might cause a deadlock. This is particularly risky when using closures within callbacks while referencing external data. Take particular care to avoid this kind of situation by making copies of data when required. The [examples/surrogate-cache-key directory](https://github.com/apollographql/router/tree/main/examples/surrogate-cache-key) contains an example of this, where "closing over" `response.headers` would cause a deadlock. To avoid this, a local copy of the required data is obtained and used in the closure. diff --git a/docs/source/enterprise-features.mdx b/docs/source/enterprise-features.mdx index f615b30902..a6a1b53352 100644 --- a/docs/source/enterprise-features.mdx +++ b/docs/source/enterprise-features.mdx @@ -1,16 +1,16 @@ --- -title: Enterprise Features of the Apollo Router -subtitle: Connect the router to GraphOS for advanced features -description: Unlock Enterprise features for the Apollo Router by connecting it to GraphOS. Enable offline licenses for extended disconnections. +title: GraphOS Router Enterprise Features +subtitle: Use expanded features of GraphOS Router enabled by an Enterprise plan +description: Unlock Enterprise features for the GraphOS Router by connecting it to Apollo GraphOS. Enable offline licenses for extended disconnections. --- -Since the Apollo Router is [source-available](https://www.apollographql.com/blog/evaluating-apollo-router-understanding-free-and-open-vs-commercial-features), you can use its codebase without connecting it to GraphOS. GraphOS organizations with the Enterprise plan can [connect a self-hosted router to GraphOS](/graphos/quickstart/self-hosted#6-connect-the-router-to-graphos) for an expanded feature set. +GraphOS organizations with the Enterprise plan can [connect a self-hosted router to GraphOS](/graphos/quickstart/self-hosted#6-connect-the-router-to-graphos) for an expanded feature set. -A router connected to GraphOS, whether cloud- or self-hosted, is called a **GraphOS router**. It has access to specific GraphOS features depending on the connected GraphOS organization's plan. Refer to the [pricing page](https://www.apollographql.com/pricing#graphos-router) to compare GraphOS router features across plan types. +A router connected to GraphOS, whether cloud- or self-hosted, is called a **GraphOS Router**. It has access to specific GraphOS features depending on the connected GraphOS organization's plan. Refer to the [pricing page](https://www.apollographql.com/pricing#graphos-router) to compare GraphOS Router features across plan types. -Try out Enterprise GraphOS router features for free with an [Enterprise trial](/graphos/org/plans/#enterprise-trials). +Try the Enterprise features of GraphOS Router for free with an [Enterprise trial](/graphos/org/plans/#enterprise-trials). @@ -28,12 +28,12 @@ For details on these features, see [this blog post](https://blog.apollographql.c ## Enabling Enterprise features -To enable support for Apollo Router Enterprise features: +To enable support for GraphOS Router Enterprise features: - Your organization must have a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). -- You must run v1.12 or later of the Apollo Router. [Download the latest version.](./quickstart#download-options) +- You must run GraphOS Router v1.12. [Download the latest version.](./quickstart#download-options) - Certain Enterprise features might require a later router version. See a particular feature's documentation for details. -- Your Apollo Router instances must connect to GraphOS with a **graph API key** and **graph ref** associated with your organization. +- Your router instances must connect to GraphOS with a **graph API key** and **graph ref** associated with your organization. - You connect your router to GraphOS by setting [these environment variables](./configuration/overview/#environment-variables) when starting the router. - If your router _already_ connects to your GraphOS Enterprise organization, no further action is required. @@ -46,7 +46,7 @@ Whenever your router instance starts up and connects to GraphOS, it fetches a ** ```mermaid flowchart LR; subgraph "Your Infrastructure"; - router(["Apollo Router"]); + router(["GraphOS Router"]); end; subgraph "GraphOS"; uplink(Apollo Uplink) @@ -72,9 +72,9 @@ Offline Enterprise license support is available on an as-needed basis. Send a re -Running your Apollo Router fleet while fully connected to GraphOS is the best choice for most Apollo users. However, some scenarios can prevent your routers from connecting to GraphOS for an extended period, ranging from disasters that break connectivity to isolated sites operating with air-gapped networks. If you need to restart or rapidly scale your entire router fleet, but you're unable to communicate with Apollo Uplink, new router instances won't be able to serve traffic. +Running your GraphOS Router fleet while fully connected to GraphOS is the best choice for most Apollo users. However, some scenarios can prevent your routers from connecting to GraphOS for an extended period, ranging from disasters that break connectivity to isolated sites operating with air-gapped networks. If you need to restart or rapidly scale your entire router fleet, but you're unable to communicate with Apollo Uplink, new router instances won't be able to serve traffic. -To support long-term disconnection scenarios, GraphOS supports **offline Enterprise licenses** for the Apollo Router. An offline license enables routers to start and serve traffic without a persistent connection to GraphOS. The functionality available with an offline license is much like being fully connected to GraphOS, including managed federation for supergraph CI (operation checks, schema linting, contracts, etc.). +To support long-term disconnection scenarios, GraphOS supports **offline Enterprise licenses** for the GraphOS Router. An offline license enables routers to start and serve traffic without a persistent connection to GraphOS. The functionality available with an offline license is much like being fully connected to GraphOS, including managed federation for supergraph CI (operation checks, schema linting, contracts, etc.). An offline license can be retrieved from GraphOS with the [`rover license fetch`](/rover/commands/license) command. @@ -88,9 +88,9 @@ A router using an offline license requires [the use of local manifests](./config An offline license is valid for the lesser of the duration of your contract with Apollo, or one year, with an added grace period of 28 days. You are responsible for keeping your offline license files up to date within your infrastructure by rerunning `rover license fetch` to fetch updated license files. -#### Set up offline license for the Apollo Router +#### Set up offline license for the GraphOS Router -Follow these steps to configure an Apollo Router to use an offline Enterprise license: +Follow these steps to configure an GraphOS Router to use an offline Enterprise license: 1. Fetch an offline license by running [`rover license fetch`](/rover/commands/license/#license-fetch) with the ID of the graph from which you want to fetch a license: @@ -123,7 +123,7 @@ Follow these steps to configure an Apollo Router to use an offline Enterprise li ### Licenses with local development -You might also need to run an Apollo Router instance on your local machine, such as with the [`rover dev`](/graphos/graphs/local-development) command. It's likely that your local router instance doesn't connect to GraphOS to get its supergraph schema from Uplink. For example, you can run `rover dev` to perform composition locally. +You might also need to run an GraphOS Router instance on your local machine, such as with the [`rover dev`](/graphos/graphs/local-development) command. It's likely that your local router instance doesn't connect to GraphOS to get its supergraph schema from Uplink. For example, you can run `rover dev` to perform composition locally. **You _can_ use Enterprise router features with a locally composed supergraph schema!** To do so, your router must still connect to GraphOS to obtain its [license](#the-enterprise-license). diff --git a/docs/source/errors.mdx b/docs/source/errors.mdx index cc5ce9ab58..5730dd6fef 100644 --- a/docs/source/errors.mdx +++ b/docs/source/errors.mdx @@ -1,10 +1,10 @@ --- -title: Errors -subtitle: Error and status codes returned by the Apollo Router -description: Reference for error and HTTP status codes returned by the Apollo Router, including explanations and solutions. +title: Router Errors +subtitle: Error and status codes returned by GraphOS Router and Apollo Router Core +description: Reference of error codes and HTTP status codes returned by Apollo GraphOS Router and Apollo Router Core, including explanations and solutions. --- -Learn about error codes and HTTP response status codes returned by the Apollo Router. +Learn about error codes and HTTP response status codes returned by GraphOS Router and Apollo Router Core. ## Status codes diff --git a/docs/source/executing-operations/defer-support.mdx b/docs/source/executing-operations/defer-support.mdx index 65e87bc208..0e6c4d76bc 100644 --- a/docs/source/executing-operations/defer-support.mdx +++ b/docs/source/executing-operations/defer-support.mdx @@ -1,13 +1,13 @@ --- -title: Apollo Router Support for @defer +title: Router Support for @defer subtitle: Improve performance by delivering fields incrementally -description: Improve your GraphQL query performance with Apollo Router's support for the @defer directive. Incrementally deliver response data by deferring certain fields. +description: Improve your GraphQL query performance with GraphOS Router and Apollo Router Core's support for the @defer directive. Incrementally deliver response data by deferring certain fields. minVersion: 1.8.0 --- -Queries sent to the Apollo Router can use the `@defer` directive to enable the incremental delivery of response data. By deferring data for some fields, the router can resolve and return data for the query's _other_ fields more quickly, improving responsiveness. +Queries sent to GraphOS Router or Apollo Router Core can use the `@defer` directive to enable the incremental delivery of response data. By deferring data for some fields, the router can resolve and return data for the query's _other_ fields more quickly, improving responsiveness. -The Apollo Router's `@defer` support is compatible with all [federation-compatible subgraph libraries](/federation/building-supergraphs/supported-subgraphs/). That's because the router takes advantage of your supergraph's existing [entities](/federation/entities/) to fetch any deferred field data via followup queries to your subgraphs. +The router's `@defer` support is compatible with all [federation-compatible subgraph libraries](/federation/building-supergraphs/supported-subgraphs/). That's because the router takes advantage of your supergraph's existing [entities](/federation/entities/) to fetch any deferred field data via followup queries to your subgraphs. ## What is `@defer`? @@ -31,19 +31,19 @@ query GetTopProducts { } ``` -To respond incrementally, the Apollo Router uses a multipart-encoded HTTP response. To use `@defer` successfully with the Apollo Router, a client's GraphQL library must _also_ support the directive by handling multipart HTTP responses correctly. +To respond incrementally, the router uses a multipart-encoded HTTP response. To use `@defer` successfully with the router, a client's GraphQL library must _also_ support the directive by handling multipart HTTP responses correctly. -The Apollo Router's `@defer` support is compatible with all [federation-compatible subgraph libraries](/federation/building-supergraphs/supported-subgraphs/), because the deferring logic exists entirely within the router itself. +The router's `@defer` support is compatible with all [federation-compatible subgraph libraries](/federation/building-supergraphs/supported-subgraphs/), because the deferring logic exists entirely within the router itself. ### Basics of `@defer` To learn the basics of the `@defer` directive and how you can use it with your supergraph, first read [Deferring query response data with GraphOS](/graphos/operations/defer). -The remainder of this article covers the Apollo Router's defer implementation in greater depth. +The remainder of this article covers the router's defer implementation in greater depth. ## Executing a `@defer` query -To execute a deferred query on the Apollo Router, a GraphQL client sends an HTTP request with _almost_ the exact same format that it uses for usual query and mutation requests. +To execute a deferred query on the router, a GraphQL client sends an HTTP request with _almost_ the exact same format that it uses for usual query and mutation requests. The only difference is that the request must include the following `Accept` header: @@ -54,9 +54,9 @@ Accept: multipart/mixed;deferSpec=20220824, application/json > Note: because the parts are always JSON, it is never possible for `\r\n--graphql` to appear in the contents of a part. For convenience, servers MAY use `graphql` as a boundary. > Clients MUST accomodate any boundary returned by the server in `Content-Type`. -## How does the Apollo Router defer fields? +## How does the router defer fields? -As discussed in [this article](/graphos/operations/defer/#which-fields-can-my-router-defer), the Apollo Router can defer the following fields in your schema: +As discussed in [this article](/graphos/operations/defer/#which-fields-can-my-router-defer), the router can defer the following fields in your schema: - Root fields of the `Query` type (along with their subfields) - Fields of any entity type (along with their subfields) @@ -210,7 +210,7 @@ Now, the router queries _the same subgraph twice_, first to fetch non-deferred f ## Non-deferrable fields -A query's `@defer` fragment might include fields that the Apollo Router _can't_ defer. The router handles this case gracefully with the following logic: +A query's `@defer` fragment might include fields that the router _can't_ defer. The router handles this case gracefully with the following logic: - The router defers every field in the fragment that it _can_ defer. - The router resolves any non-deferrable fields in the fragment _before_ sending its initial response to the client. @@ -270,11 +270,11 @@ In this case, the router must internally resolve each author's list of associate The `@defer` directive is currently part of a draft-stage RFC for the GraphQL specification ([learn about RFC contribution stages](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md#rfc-contribution-stages)). -The Apollo Router supports the `@defer` directive as it's documented in [these edits to the RFC](https://github.com/graphql/graphql-spec/pull/742), according to the state of those edits on 2022-08-24. +The router supports the `@defer` directive as it's documented in [these edits to the RFC](https://github.com/graphql/graphql-spec/pull/742), according to the state of those edits on 2022-08-24. ## Disabling `@defer` -Defer support is enabled in the Apollo Router by default. To _disable_ support, add `defer_support: false` to your router's [YAML config file](../configuration/overview/#yaml-config-file) under the `supergraph` key: +Defer support is enabled in the router by default. To _disable_ support, add `defer_support: false` to your router's [YAML config file](../configuration/overview/#yaml-config-file) under the `supergraph` key: ```yaml title="router.yaml" supergraph: diff --git a/docs/source/executing-operations/file-uploads.mdx b/docs/source/executing-operations/file-uploads.mdx index 4e2ca4b73a..7b488fb28e 100644 --- a/docs/source/executing-operations/file-uploads.mdx +++ b/docs/source/executing-operations/file-uploads.mdx @@ -1,7 +1,7 @@ --- title: File uploads -subtitle: Receive files uploaded by clients with the Apollo Router -description: Configure the Apollo Router to receive file uploads using the GraphQL multipart request spec. +subtitle: Receive files uploaded by clients with the GraphOS Router +description: Configure the GraphOS Router to receive file uploads using the GraphQL multipart request spec. minVersion: 1.41.1 noIndex: true --- @@ -12,7 +12,7 @@ This feature is in invite-only [preview](/resources/product-launch-stages/#produ -Learn how to configure the Apollo Router to receive file uploads in client requests using the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec). +Learn how to configure the GraphOS Router to receive file uploads in client requests using the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec). ## About file uploads using multipart requests @@ -73,11 +73,11 @@ The exact requirements are documented in [Client usage requirements](#client-usa ## File upload configuration and usage -To enable file uploads from clients, you must both [configure support in the Apollo Router](#configure-file-upload-support-in-the-router) and [ensure client usage conforms to requirements](#client-usage-requirements). +To enable file uploads from clients, you must both [configure support in the GraphOS Router](#configure-file-upload-support-in-the-router) and [ensure client usage conforms to requirements](#client-usage-requirements). ### Configure file upload support in the router -By default, receiving client file uploads isn't enabled in the Apollo Router. +By default, receiving client file uploads isn't enabled in the GraphOS Router. To enable file upload support, set the following fields in your `router.yaml` configuration file: ```yaml title="router.yaml" @@ -134,7 +134,7 @@ The following are attributes of the root [`preview_file_uploads`](#configure-fil
Attribute/
Description		Default ValueDefault value Valid Values
diff --git a/docs/source/executing-operations/query-batching.mdx b/docs/source/executing-operations/query-batching.mdx index 7676c710cd..739f68e1d6 100644 --- a/docs/source/executing-operations/query-batching.mdx +++ b/docs/source/executing-operations/query-batching.mdx @@ -1,12 +1,12 @@ --- title: Query Batching -subtitle: Receive query batches with the Apollo Router -description: Handle multiple GraphQL requests with Apollo Router's query batching capabilities. Aggregate operations into single HTTP requests, reducing overhead. +subtitle: Receive query batches with the GraphOS Router +description: Handle multiple GraphQL requests with GraphOS Router's query batching capabilities. Aggregate operations into single HTTP requests, reducing overhead. --- -Learn about query batching and how to configure the Apollo Router to receive query batches. +Learn about query batching and how to configure the GraphOS Router to receive query batches. ## About query batching @@ -20,23 +20,23 @@ With client batching, the router accepts batched requests from a client and proc With subgraph batching, the router analyzes input client batch requests and issues batch requests to subgraphs. Subgraph batching is an extension to client batching and requires participating subgraphs to support batching requests. See the examples below to see illustrations of how this works in practice. -The Apollo Router supports client and subgraph query batching. +The GraphOS Router supports client and subgraph query batching. If you’re using Apollo Client, you can leverage the built-in support for batching to reduce the number of individual operations sent to the router. Once configured, Apollo Client automatically combines multiple operations into a single HTTP request. The number of operations within a batch is client-configurable, including the maximum number in a batch and the maximum duration to wait for operations to accumulate before sending the batch. -The Apollo Router must be configured to receive query batches, otherwise it rejects them. When processing a batch, the router deserializes and processes each operation of a batch independently. It responds to the client only after all operations of the batch have been completed. Each operation executes concurrently with respect to other operations in the batch. +The GraphOS Router must be configured to receive query batches, otherwise it rejects them. When processing a batch, the router deserializes and processes each operation of a batch independently. It responds to the client only after all operations of the batch have been completed. Each operation executes concurrently with respect to other operations in the batch. ## Configure client query batching -Both the Apollo Router and client need to be configured to support query batching. +Both the GraphOS Router and client need to be configured to support query batching. ### Configure router #### Client query batching -By default, receiving client query batches is _not_ enabled in the Apollo Router. +By default, receiving client query batches is _not_ enabled in the GraphOS Router. To enable query batching, set the following fields in your `router.yaml` configuration file: @@ -193,7 +193,7 @@ If the router receives a query batch from a client, and batching is *not* enable ## Metrics for query batching -Metrics in the Apollo Router for query batching: +Metrics in the GraphOS Router for query batching:
diff --git a/docs/source/executing-operations/requests.mdx b/docs/source/executing-operations/requests.mdx index db6f9f88b2..fff8c3eadd 100644 --- a/docs/source/executing-operations/requests.mdx +++ b/docs/source/executing-operations/requests.mdx @@ -1,16 +1,16 @@ --- title: Operation Request Format -subtitle: Send requests to the Apollo Router over HTTP -description: Learn how to format and send GraphQL requests to Apollo Router over HTTP. Explore POST and GET examples and the automatic persisted queries protocol. +subtitle: Send requests to the router over HTTP +description: Learn how to format and send GraphQL requests to Apollo GraphOS Router or Apollo Router Core over HTTP. Explore POST and GET examples and the automatic persisted queries protocol. --- -By default, almost every GraphQL IDE and client library takes care of sending operations in a format that the Apollo Router supports. This article describes that format, which is also described on [graphql.org](https://graphql.org/learn/serving-over-http/) and in [this preliminary spec](https://github.com/graphql/graphql-over-http). +By default, almost every GraphQL IDE and client library takes care of sending operations in a format that the GraphOS Router or Apollo Router Core supports. This article describes that format, which is also described on [graphql.org](https://graphql.org/learn/serving-over-http/) and in [this preliminary spec](https://github.com/graphql/graphql-over-http). -The Apollo Router accepts queries, mutations, and subscriptions sent as POST requests. It also accepts queries sent as GET requests. +The router accepts queries, mutations, and subscriptions sent as POST requests. It also accepts queries sent as GET requests. ## POST requests -The Apollo Router accepts POST requests with a JSON body. A valid request contains a `query` field, along with optional `variables` and an `operationName` (if `query` contains multiple possible operations). +The router accepts POST requests with a JSON body. A valid request contains a `query` field, along with optional `variables` and an `operationName` (if `query` contains multiple possible operations). Let's say we want to execute the following query: @@ -43,13 +43,13 @@ curl --request POST \ https://rover.apollo.dev/quickstart/products/graphql ``` -The Apollo Router's default landing page provides a `curl` command you can use to execute a test query on your own server: +The router's default landing page provides a `curl` command you can use to execute a test query on your own server: ## GET requests -The Apollo Router also accepts GET requests for queries (but not mutations). With a GET request, query details (`query`, `operationName`, `variables`) are provided as URL query parameters. The `variables` option is a URL-escaped JSON object. +The router also accepts GET requests for queries (but not mutations). With a GET request, query details (`query`, `operationName`, `variables`) are provided as URL query parameters. The `variables` option is a URL-escaped JSON object. Here's the same query from [POST requests](#post-requests) formatted for a `curl` GET request: @@ -60,7 +60,7 @@ curl --request GET \ ## Persisted queries protocol -The Automatic Persisted Queries (APQ) and Persisted Query List (PQL) features of the Apollo Router use a separate protocol to send the operation document information in the `extensions`. This protocal can also use HTTP POST or GET. See the Apollo Client docs on the [APQ protocol](/react/api/link/persisted-queries/#protocol) for details. +The Automatic Persisted Queries (APQ) feature available for Apollo Router Core and the Persisted Query List (PQL) feature available for GraphOS Router use a separate protocol to send the operation document information in the `extensions`. This protocol can also use HTTP POST or GET. See the Apollo Client docs on the [APQ protocol](/react/api/link/persisted-queries/#protocol) for details. ## Related topics diff --git a/docs/source/executing-operations/subscription-callback-protocol.mdx b/docs/source/executing-operations/subscription-callback-protocol.mdx index 573ad2f723..0f4c3e743c 100644 --- a/docs/source/executing-operations/subscription-callback-protocol.mdx +++ b/docs/source/executing-operations/subscription-callback-protocol.mdx @@ -1,18 +1,18 @@ --- title: HTTP Callback Protocol for GraphQL Subscriptions subtitle: Enable clients to receive real-time updates via HTTP callback -description: Understand the HTTP Callback Protocol for GraphQL Subscriptions with the Apollo Router. Learn initialization, main loop, message types, and error handling. +description: Understand the HTTP Callback Protocol for GraphQL Subscriptions with the GraphOS Router. Learn initialization, main loop, message types, and error handling. --- -This reference describes a protocol for GraphQL servers (or **subgraphs**) to send subscription data to a subscribing **graph router** (such as the Apollo Router) via HTTP callbacks. Use this reference if you're adding support for this protocol to a GraphQL server library or other system. +This reference describes a protocol for GraphQL servers (or **subgraphs**) to send subscription data to a subscribing **graph router** (such as the GraphOS Router) via HTTP callbacks. Use this reference if you're adding support for this protocol to a GraphQL server library or other system. For routers with many simultaneous open subscriptions, this protocol scales better than WebSocket-based protocols, which require long-lasting open connections. -The Apollo Router provides [support for this protocol](./subscription-support/#http-callback-setup) as part of its support for federated subscriptions: +The GraphOS Router provides [support for this protocol](./subscription-support/#http-callback-setup) as part of its support for federated subscriptions: ```mermaid sequenceDiagram - participant Router as Apollo Router
(subscriber) + participant Router as GraphOS Router
(subscriber) participant Subgraph as Subgraph Router->>Subgraph: Registers subscription and
callback URL over HTTP Note over Subgraph: New data available diff --git a/docs/source/executing-operations/subscription-multipart-protocol.mdx b/docs/source/executing-operations/subscription-multipart-protocol.mdx index 3842f3a382..6dad6feaf2 100644 --- a/docs/source/executing-operations/subscription-multipart-protocol.mdx +++ b/docs/source/executing-operations/subscription-multipart-protocol.mdx @@ -1,16 +1,16 @@ --- title: Multipart HTTP protocol for GraphQL Subscriptions subtitle: Enable clients to receive real-time updates via multipart HTTP protocol -description: Enable real-time updates via multipart HTTP protocol for GraphQL subscriptions with the Apollo Router. Learn about execution, heartbeats, and error handling. +description: Enable real-time updates via multipart HTTP protocol for GraphQL subscriptions with the GraphOS Router. Learn about execution, heartbeats, and error handling. --- -To execute GraphQL subscription operations on the Apollo Router, client apps do _not_ communicate over WebSocket. Instead, they use **HTTP with multipart responses**. This multipart protocol is built on the same [Incremental Delivery over HTTP](https://github.com/graphql/graphql-over-http/blob/main/rfcs/IncrementalDelivery.md) spec that the Apollo Router uses to support [the `@defer` directive](./defer-support/). +To execute GraphQL subscription operations on the GraphOS Router, client apps do _not_ communicate over WebSocket. Instead, they use **HTTP with multipart responses**. This multipart protocol is built on the same [Incremental Delivery over HTTP](https://github.com/graphql/graphql-over-http/blob/main/rfcs/IncrementalDelivery.md) spec that the GraphOS Router uses to support [the `@defer` directive](./defer-support/). Use this reference if you're adding protocol support to a new GraphQL client library. [Apollo Client](/react/data/subscriptions#http), [Apollo Kotlin](/kotlin/essentials/subscriptions#configuring-http-subscriptions), and [Apollo iOS](/ios/fetching/subscriptions#http) all support this protocol. Apollo Client also provides network adapters for the [Relay](/react/data/subscriptions#relay) and [urql](/react/data/subscriptions#urql) libraries. ## Executing a subscription -To execute a subscription on the Apollo Router, a GraphQL client sends an HTTP request with _almost_ the exact same format that it uses for query and mutation requests. +To execute a subscription on the GraphOS Router, a GraphQL client sends an HTTP request with _almost_ the exact same format that it uses for query and mutation requests. The only difference is that the request should include the following `Accept` header: @@ -45,7 +45,7 @@ Content-Type: application/json ## Heartbeats -While a client subscription remains active, the Apollo Router sends periodic "heartbeat" response parts to prevent any intermediaries from closing the connection. The body of a heartbeat is an empty JSON object, which clients should ignore silently: +While a client subscription remains active, the GraphOS Router sends periodic "heartbeat" response parts to prevent any intermediaries from closing the connection. The body of a heartbeat is an empty JSON object, which clients should ignore silently: ```text title="Heartbeat response part" --graphql @@ -61,7 +61,7 @@ This protocol differentiates between transport-level errors and GraphQL errors i With the exception of [heartbeats](#heartbeats), every response part body includes a `payload` property, which contains standard GraphQL response properties. **The `payload` property can be null if a transport-level error occurs.** -**If a GraphQL-level error occurs,** the Apollo Router can sometimes still return partial data, and the subscription connection should remain open. These errors are provided _within_ the `payload` property: +**If a GraphQL-level error occurs,** the GraphOS Router can sometimes still return partial data, and the subscription connection should remain open. These errors are provided _within_ the `payload` property: ```json { diff --git a/docs/source/federation-version-support.mdx b/docs/source/federation-version-support.mdx index c53ebe3556..195e9b0018 100644 --- a/docs/source/federation-version-support.mdx +++ b/docs/source/federation-version-support.mdx @@ -1,10 +1,10 @@ --- -title: Federation Version Support in the Apollo Router +title: Federation Version Support subtitle: Check router version compatibility with Apollo Federation versions -description: This reference shows which version of Apollo Federation each Apollo Router release is compiled against. Ensure your router uses at least the listed federation version. +description: This reference shows which version of Apollo Federation each GraphOS Router and Apollo Router Core release is compiled against. Ensure your router uses at least the listed federation version. --- -The Apollo Router supports supergraph schemas that are generated via Apollo Federation 2.x [composition](/federation/federated-types/composition/). This composition algorithm is usually performed by one of the following: +The GraphOS Router and Apollo Router Core support supergraph schemas that are generated via Apollo Federation 2.x [composition](/federation/federated-types/composition/). This composition algorithm is usually performed by one of the following: * Apollo GraphOS (for supergraphs that use [managed federation](/federation/managed-federation/overview/)) * The Rover CLI (for _non_-managed supergraphs) @@ -53,7 +53,7 @@ The table below shows which version of federation each router release is compile
- v1.46.0 - v1.47.0 + v1.46.0 - v1.47.0 2.7.5 @@ -371,6 +371,6 @@ The table below shows which version of federation each router release is compile ## Federation 1 support -Federation 2.x composition is backward compatible with Federation 1.x subgraph schemas, so you can use the Apollo Router with any valid Federation 1.x supergraph. +Federation 2.x composition is backward compatible with Federation 1.x subgraph schemas, so you can use the router with any valid Federation 1.x supergraph. -If your Federation 1.x supergraph _doesn't_ work with the Apollo Router, see possible causes in [Backward compatibility in Federation 2](/federation/federation-2/backward-compatibility/). +If your Federation 1.x supergraph _doesn't_ work with the router, see possible causes in [Backward compatibility in Federation 2](/federation/federation-2/backward-compatibility/). diff --git a/docs/source/index.mdx b/docs/source/index.mdx index c4aaf69172..7dbcd70870 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -1,18 +1,22 @@ --- -title: The Apollo Router -subtitle: High-performance routing for self-hosted supergraphs -description: Distribute operations efficiently across microservices in your federated GraphQL API with the Apollo Router. Configure caching, security features, and more. +title: Self-Hosted Router +subtitle: High-performance routing with self-hosted supergraph runtimes +description: Distribute operations efficiently across microservices in your federated GraphQL API with the Apollo GraphOS Router or Apollo Router Core. Configure caching, security features, and more. --- import { Link } from 'gatsby'; -**The Apollo Router** is a configurable, high-performance router for your federated GraphQL API (also known as a [supergraph](/graphos/graphs/#self-hosted-supergraphs)): +> 💡 Not self-hosting your router? Get started with [Cloud Router](/graphos/quickstart/cloud/). + +GraphOS Router is a scalable runtime for supergraphs that's fully integrated with GraphOS and based on the Apollo Router Core. + +A self-hosted GraphOS Router or Apollo Router Core enables full management of your supergraph runtime infrastructure and deployments. ```mermaid flowchart LR; clients(Clients); subgraph "Your infrastructure"; - router(["Apollo Router"]); + router(["Router"]); serviceB[Products
API]; serviceC[Reviews
API]; router -->|Sub-query| serviceB & serviceC; @@ -21,11 +25,12 @@ flowchart LR; class clients secondary; ``` -The Apollo Router intelligently distributes inbound queries across your GraphQL-powered microservices, enabling clients to fetch data from multiple sources with a single request. +The router intelligently distributes inbound queries across your GraphQL-powered microservices, enabling clients to fetch data from multiple sources with a single request. -> Learn about the [distinction between the Apollo Router and API gateways](/technotes/TN0037-api-gateways/). +> Learn about the [distinction between the router and an API gateway](/technotes/TN0037-api-gateways/). -If you have an existing federated graph that currently uses `@apollo/gateway`, you can move to the Apollo Router without changing any other part of your graph. + +If you have an existing federated graph that currently uses `@apollo/gateway`, you can move to the router without changing any other part of your graph.