feat(composition): @openfed__requestScoped directive

Author: SkArchon

composition/src/directive-definition-data/directive-definition-data.ts

@@ -88,6 +88,7 @@ import {
   MAX_AGE,
   NEGATIVE_CACHE_TTL,
   PARTIAL_CACHE_LOAD,
+  REQUEST_SCOPED,
   SHADOW_MODE,
 } from '../utils/string-constants';
 import {
@@ -123,6 +124,7 @@ import {
   CACHE_INVALIDATE_DEFINITION,
   CACHE_POPULATE_DEFINITION,
   ENTITY_CACHE_DEFINITION,
+  REQUEST_SCOPED_DEFINITION,
   SPECIFIED_BY_DEFINITION,
   SUBSCRIPTION_FILTER_DEFINITION,
   TAG_DEFINITION,
@@ -1044,3 +1046,21 @@ export const CACHE_POPULATE_DEFINITION_DATA = newDirectiveDefinitionData({
   node: CACHE_POPULATE_DEFINITION,
   optionalArgumentNames: new Set<ArgumentName>([MAX_AGE]),
 });
+export const REQUEST_SCOPED_DEFINITION_DATA = newDirectiveDefinitionData({
+  argumentDataByName: new Map<ArgumentName, DirectiveArgumentData>([
+    [
+      KEY,
+      newDirectiveArgumentData({
+        directive: `@${REQUEST_SCOPED}`,
+        name: KEY,
+        namedTypeKind: Kind.SCALAR_TYPE_DEFINITION,
+        typeNode: REQUIRED_STRING_TYPE_NODE,
+      }),
+    ],
+  ]),
+  locations: new Set<DirectiveLocation>([FIELD_DEFINITION_UPPER]),
+  name: REQUEST_SCOPED,
+  node: REQUEST_SCOPED_DEFINITION,
+  requiredArgumentNames: new Set<ArgumentName>([KEY]),
+});
+

composition/src/router-configuration/types.ts

@@ -86,6 +86,17 @@ export type RequiredFieldConfiguration = {
   disableEntityResolver?: boolean;
 };
 
+export type RequestScopedFieldConfig = {
+  fieldName: FieldName;
+  typeName: TypeName;
+  // L1 cache key used to store/lookup this field's value for the duration of a request.
+  // Format: "{subgraphName}.{key}" where `key` is the @openfed__requestScoped(key:) argument.
+  // All fields in the same subgraph declaring @openfed__requestScoped with the same key share
+  // the same L1 entry — the first one to resolve populates it, subsequent ones inject
+  // from it (subject to widening checks and alias-aware normalization).
+  l1Key: string;
+};
+
 export type ConfigurationData = {
   fieldNames: Set<FieldName>;
   isRootNode: boolean;
@@ -144,6 +155,7 @@ export type EntityCachingConfiguration = {
   cacheInvalidateConfigurations?: Array<CacheInvalidateConfig>;
   // Attached to the Mutation/Subscription type's ConfigurationData from @openfed__cachePopulate.
   cachePopulateConfigurations?: Array<CachePopulateConfig>;
+  requestScopedFields?: Array<RequestScopedFieldConfig>;
 };
 
 export type Costs = {

composition/src/utils/string-constants.ts

@@ -132,6 +132,7 @@ export const REASON = 'reason';
 export const REQUEST = 'request';
 export const REQUIRE_FETCH_REASONS = 'openfed__requireFetchReasons';
 export const REQUIRE_ONE_SLICING_ARGUMENT = 'requireOneSlicingArgument';
+export const REQUEST_SCOPED = 'openfed__requestScoped';
 export const REQUIRES = 'requires';
 export const REQUIRES_SCOPES = 'requiresScopes';
 export const RESOLVABLE = 'resolvable';

composition/src/v1/constants/constants.ts

@@ -10,6 +10,7 @@ import {
   CACHE_POPULATE,
   COST,
   ENTITY_CACHE,
+  REQUEST_SCOPED,
   DEPRECATED,
   EDFS_KAFKA_PUBLISH,
   EDFS_KAFKA_SUBSCRIBE,
@@ -80,6 +81,7 @@ import {
   CACHE_INVALIDATE_DEFINITION,
   CACHE_POPULATE_DEFINITION,
   ENTITY_CACHE_DEFINITION,
+  REQUEST_SCOPED_DEFINITION,
 } from './directive-definitions';
 
 export const DIRECTIVE_DEFINITION_BY_NAME: ReadonlyMap<DirectiveName, DirectiveDefinitionNode> = new Map<
@@ -95,6 +97,7 @@ export const DIRECTIVE_DEFINITION_BY_NAME: ReadonlyMap<DirectiveName, DirectiveD
   [ENTITY_CACHE, ENTITY_CACHE_DEFINITION],
   [CACHE_INVALIDATE, CACHE_INVALIDATE_DEFINITION],
   [CACHE_POPULATE, CACHE_POPULATE_DEFINITION],
+  [REQUEST_SCOPED, REQUEST_SCOPED_DEFINITION],
   [DEPRECATED, DEPRECATED_DEFINITION],
   [EDFS_KAFKA_PUBLISH, EDFS_KAFKA_PUBLISH_DEFINITION],
   [EDFS_KAFKA_SUBSCRIBE, EDFS_KAFKA_SUBSCRIBE_DEFINITION],

composition/src/v1/constants/directive-definitions.ts

@@ -88,6 +88,7 @@ import {
   MAX_AGE,
   NEGATIVE_CACHE_TTL,
   PARTIAL_CACHE_LOAD,
+  REQUEST_SCOPED,
   SHADOW_MODE,
 } from '../../utils/string-constants';
 import { REQUIRED_FIELDSET_TYPE_NODE, REQUIRED_INT_TYPE_NODE, REQUIRED_STRING_TYPE_NODE } from './type-nodes';
@@ -888,3 +889,20 @@ export const CACHE_POPULATE_DEFINITION: DirectiveDefinitionNode = {
   name: stringToNameNode(CACHE_POPULATE),
   repeatable: false,
 };
+export const REQUEST_SCOPED_DEFINITION: DirectiveDefinitionNode = {
+  arguments: [
+    {
+      kind: Kind.INPUT_VALUE_DEFINITION,
+      name: stringToNameNode(KEY),
+      type: {
+        kind: Kind.NON_NULL_TYPE,
+        type: stringToNamedTypeNode(STRING_SCALAR),
+      },
+    },
+  ],
+  kind: Kind.DIRECTIVE_DEFINITION,
+  locations: stringArrayToNameNodeArray([FIELD_DEFINITION_UPPER]),
+  name: stringToNameNode(REQUEST_SCOPED),
+  repeatable: false,
+};
+

composition/src/v1/normalization/normalization-factory.ts

@@ -193,6 +193,7 @@ import {
   type CacheInvalidateConfig,
   type CachePopulateConfig,
   type EntityCacheConfig,
+  type RequestScopedFieldConfig,
 } from '../../router-configuration/types';
 import { printTypeNode } from '@graphql-tools/merge';
 import {
@@ -205,6 +206,7 @@ import {
   nonExternalConditionalFieldWarning,
   singleSubgraphInputFieldOneOfWarning,
   unimplementedInterfaceOutputTypeWarning,
+  requestScopedSingleFieldWarning,
 } from '../warnings/warnings';
 import { upsertDirectiveSchemaAndEntityDefinitions, upsertParentsAndChildren } from './walkers';
 import {
@@ -357,6 +359,7 @@ import {
   MAX_AGE,
   NEGATIVE_CACHE_TTL,
   PARTIAL_CACHE_LOAD,
+  REQUEST_SCOPED,
   SHADOW_MODE,
 } from '../../utils/string-constants';
 import { MAX_INT32 } from '../../utils/integer-constants';
@@ -390,6 +393,7 @@ import {
   type ValidateDirectiveParams,
   type CachePopulateDirectiveNode,
   type EntityCacheDirectiveNode,
+  type RequestScopedDirectiveNode,
 } from './types/types';
 import { newConfigurationData, newFieldSetConditionData } from '../../router-configuration/utils';
 import { type ImplementationErrors, type InvalidFieldImplementation } from '../../utils/types';
@@ -4239,6 +4243,83 @@ export class NormalizationFactory {
     };
   }
 
+  extractRequestScopedFields() {
+    // Gather fields annotated with @openfed__requestScoped across all types in this subgraph.
+    // A field is both a reader and writer of the coordinate L1 — no receiver/provider.
+    // Fields with the same `key` share the same L1 entry: whichever is resolved first
+    // populates it, subsequent ones inject from it.
+    type Collected = {
+      typeName: string;
+      fieldName: string;
+      fieldCoords: string;
+      key: string;
+      l1Key: string;
+    };
+    const collected: Array<Collected> = [];
+
+    for (const [, parentData] of this.parentDefinitionDataByTypeName) {
+      if (parentData.kind !== Kind.OBJECT_TYPE_DEFINITION && parentData.kind !== Kind.INTERFACE_TYPE_DEFINITION) {
+        continue;
+      }
+      const typeName = getParentTypeName(parentData);
+      for (const [fieldName, fieldData] of parentData.fieldDataByName) {
+        const directives = fieldData.directivesByName.get(REQUEST_SCOPED);
+        if (!directives) {
+          continue;
+        }
+        // validateDirectives() (run earlier in normalize()) has already guaranteed a single, non-repeated
+        // @openfed__requestScoped with a required String `key`, so the generic ConstDirectiveNode can be
+        // narrowed to the precise typed node — mirroring handleComposeDirective()/ComposeDirectiveNode.
+        const directive = directives[0] as RequestScopedDirectiveNode;
+        const keyArg = directive.arguments.find((arg) => arg.name.value === KEY);
+        if (!keyArg) {
+          continue;
+        }
+
+        const fieldCoords = `${typeName}.${fieldName}`;
+        const key = keyArg.value.value;
+        const l1Key = `${this.subgraphName}.${key}`;
+        collected.push({ typeName, fieldName, fieldCoords, key, l1Key });
+      }
+    }
+
+    if (collected.length === 0) {
+      return;
+    }
+
+    // Warn when a key is used on only one field — @openfed__requestScoped is meaningless
+    // unless >= 2 fields share the key (there'd be no second reader to benefit).
+    const coordsByKey = new Map<string, Array<string>>();
+    for (const c of collected) {
+      getValueOrDefault(coordsByKey, c.key, () => []).push(c.fieldCoords);
+    }
+    for (const [key, coordsList] of coordsByKey) {
+      if (coordsList.length == 1) {
+        this.warnings.push(
+          requestScopedSingleFieldWarning({
+            subgraphName: this.subgraphName,
+            key,
+            fieldCoords: coordsList[0],
+          }),
+        );
+      }
+    }
+
+    // Group by type and attach to configurationData.
+    const byType = new Map<string, Array<RequestScopedFieldConfig>>();
+    for (const c of collected) {
+      const list = byType.get(c.typeName) ?? [];
+      list.push({ fieldName: c.fieldName, typeName: c.typeName, l1Key: c.l1Key });
+      byType.set(c.typeName, list);
+    }
+    for (const [typeName, fields] of byType) {
+      const configurationData = getValueOrDefault(this.configurationDataByTypeName, typeName, () =>
+        newConfigurationData(false, typeName),
+      );
+      configurationData.entityCaching = { ...configurationData.entityCaching, requestScopedFields: fields };
+    }
+  }
+
   addFieldNamesToConfigurationData(fieldDataByFieldName: Map<string, FieldData>, configurationData: ConfigurationData) {
     const externalFieldNames = new Set<string>();
     for (const [fieldName, fieldData] of fieldDataByFieldName) {
@@ -4512,6 +4593,8 @@ export class NormalizationFactory {
     // per-field caching directives (@openfed__cacheInvalidate etc.) — must run after entityCache
     // (reads entityCacheConfigByTypeName)
     this.processRootFieldCacheDirectives();
+    // this is where @openfed__requestScoped configurations are added to the ConfigurationData
+    this.extractRequestScopedFields();
     // Check that explicitly defined operations types are valid objects and that their fields are also valid
     for (const operationType of Object.values(OperationTypeNode)) {
       const operationTypeNode = this.schemaData.operationTypes.get(operationType);

composition/src/v1/normalization/types/types.ts

@@ -138,6 +138,20 @@ export type ComposeDirectiveArgumentNode = {
   readonly loc?: Location;
 };
 
+export type RequestScopedDirectiveNode = {
+  readonly arguments: ReadonlyArray<RequestScopedArgumentNode>;
+  readonly kind: Kind.DIRECTIVE;
+  readonly name: NameNode;
+  readonly loc?: Location;
+};
+
+export type RequestScopedArgumentNode = {
+  readonly kind: Kind.ARGUMENT;
+  readonly name: NameNode;
+  readonly value: StringValueNode; // key: String! — guaranteed by validateDirectives()
+  readonly loc?: Location;
+};
+
 export type EntityCacheDirectiveNode = {
   readonly arguments: ReadonlyArray<EntityCacheArgumentNode>;
   readonly kind: Kind.DIRECTIVE;

composition/src/v1/normalization/utils.ts

@@ -79,6 +79,7 @@ import {
   CACHE_INVALIDATE_DEFINITION_DATA,
   CACHE_POPULATE_DEFINITION_DATA,
   ENTITY_CACHE_DEFINITION_DATA,
+  REQUEST_SCOPED_DEFINITION_DATA,
 } from '../../directive-definition-data/directive-definition-data';
 import {
   AS,
@@ -91,6 +92,7 @@ import {
   CACHE_POPULATE,
   COST,
   ENTITY_CACHE,
+  REQUEST_SCOPED,
   DEPRECATED,
   EDFS_KAFKA_PUBLISH,
   EDFS_KAFKA_SUBSCRIBE,
@@ -482,6 +484,7 @@ export function initializeDirectiveDefinitionDatas(): Map<string, DirectiveDefin
     [ENTITY_CACHE, ENTITY_CACHE_DEFINITION_DATA],
     [CACHE_INVALIDATE, CACHE_INVALIDATE_DEFINITION_DATA],
     [CACHE_POPULATE, CACHE_POPULATE_DEFINITION_DATA],
+    [REQUEST_SCOPED, REQUEST_SCOPED_DEFINITION_DATA],
     [DEPRECATED, DEPRECATED_DEFINITION_DATA],
     [EDFS_KAFKA_PUBLISH, KAFKA_PUBLISH_DEFINITION_DATA],
     [EDFS_KAFKA_SUBSCRIBE, KAFKA_SUBSCRIBE_DEFINITION_DATA],

composition/src/v1/warnings/params.ts

@@ -16,3 +16,9 @@ export type InvalidRepeatedComposedDirectiveWarningParams = {
   directiveName: DirectiveName;
   printedDirective: string;
 };
+
+export type RequestScopedSingleFieldWarningParams = {
+  subgraphName: SubgraphName;
+  key: string;
+  fieldCoords: FieldName;
+};

composition/src/v1/warnings/warnings.ts

@@ -2,6 +2,7 @@ import { Warning } from '../../warnings/types';
 import { QUOTATION_JOIN } from '../../utils/string-constants';
 import {
   type InvalidRepeatedComposedDirectiveWarningParams,
+  type RequestScopedSingleFieldWarningParams,
   type SingleFederatedInputFieldOneOfWarningParams,
   type SingleSubgraphInputFieldOneOfWarningParams,
 } from './params';
@@ -236,3 +237,19 @@ export function invalidRepeatedComposedDirectiveWarning({
     },
   });
 }
+
+export function requestScopedSingleFieldWarning({
+  subgraphName,
+  key,
+  fieldCoords,
+}: RequestScopedSingleFieldWarningParams): Warning {
+  return new Warning({
+    message:
+      `@openfed__requestScoped(key: "${key}") is declared on only one field ("${fieldCoords}") in this subgraph.` +
+      ` The directive is meaningless unless at least 2 fields share the same key so that the second` +
+      ` and subsequent fields can be served from the per-request L1 cache populated by the first.`,
+    subgraph: {
+      name: subgraphName,
+    },
+  });
+}