Skip to content
Back to search

apollo-marketplace

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/apollographql--skills/badge.svg)](/listings/apollographql--skills)

HTML

<a href="/listings/apollographql--skills"><img src="/api/listings/apollographql--skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install skills using the [Skills CLI](https://skills.sh/docs/cli):

npx skills add apollographql/skills

The CLI guides you through an interactive installation:

1. **Select skills** - Choose which skills to install 2. **Select agents** - Pick target agents (Claude Code, Codex, Cursor, Gemini CLI, Goose, OpenCode) 3. **Installation scope** - Project (committed with your code) or Global 4. **Installation method** - Symlink (recommended) or Copy

◇  Found 11 skills
│
◆  Select skills to install
│  ◼ apollo-client
│  ◼ apollo-connectors
│  ◼ apollo-server
│  ○ ...
└

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "apollo-marketplace",
  3. "owner": {
  4. "name": "Apollo GraphQL",
  5. "email": "opensource@apollographql.com"
  6. },
  7. "metadata": {
  8. "description": "Bundled plugins for GraphQL development with Apollo tools and technologies",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "apollo-skills",
  14. "source": "./"
  15. }
  16. ]
  17. }
README.md · README · 712 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Apollo GraphQL Agent Skills
  2. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  3. [![Skills](https://img.shields.io/badge/skills-11-green.svg)](#skills)
  4. A collection of skills for AI coding agents working with Apollo GraphQL tools and technologies.
  5. Apollo Skills follow the [Agent Skills](https://agentskills.io/) format and are available on [skills.sh](https://skills.sh/).
  6. ## Installation
  7. Install skills using the [Skills CLI](https://skills.sh/docs/cli):
  8. ```bash
  9. npx skills add apollographql/skills
  10. ```
  11. The CLI guides you through an interactive installation:
  12. 1. **Select skills** - Choose which skills to install
  13. 2. **Select agents** - Pick target agents (Claude Code, Codex, Cursor, Gemini CLI, Goose, OpenCode)
  14. 3. **Installation scope** - Project (committed with your code) or Global
  15. 4. **Installation method** - Symlink (recommended) or Copy
  16. ```
  17. ◇ Found 11 skills
  18. │
  19. ◆ Select skills to install
  20. │ ◼ apollo-client
  21. │ ◼ apollo-connectors
  22. │ ◼ apollo-server
  23. │ ○ ...
  24. └
  25. ```
  26. ## Claude Code Plugin
  27. You can also install skills as a [Claude Code plugin](https://code.claude.com/docs/en/discover-plugins):
  28. First, add the marketplace:
  29. ```bash
  30. /plugin marketplace add apollographql/skills
  31. ```
  32. Then, install the plugin:
  33. ```bash
  34. /plugin install apollo-skills@apollo-marketplace
  35. ```
  36. Once installed, skills are available as namespaced slash commands:
  37. | Slash Command | Description |
  38. |---|---|
  39. | `/apollo-skills:apollo-client` | Apollo Client 4.x for React — queries, mutations, caching, local state |
  40. | `/apollo-skills:apollo-connectors` | **Deprecated** — use [`/apollo-skills:graphos-factory`](#graphos-factory) instead |
  41. | `/apollo-skills:apollo-ios` | Apollo iOS — GraphQL client for Swift (iOS, macOS, tvOS, watchOS, visionOS) |
  42. | `/apollo-skills:apollo-kotlin` | Apollo Kotlin — GraphQL client for Android and Kotlin |
  43. | `/apollo-skills:apollo-mcp-server` | Apollo MCP Server — connect AI agents with GraphQL APIs |
  44. | `/apollo-skills:apollo-server` | Apollo Server 4.x — schemas, resolvers, auth, plugins |
  45. | `/apollo-skills:graphos-factory` | GraphOS Factory — build and iterate on an Apollo Connectors subgraph from a REST API |
  46. | `/apollo-skills:graphql-operations` | GraphQL operations — queries, mutations, fragments |
  47. | `/apollo-skills:graphql-schema` | GraphQL schema design — types, naming, pagination, errors |
  48. | `/apollo-skills:rover` | Rover CLI — schema management and local supergraph development |
  49. | `/apollo-skills:rust-best-practices` | Rust best practices — idiomatic Rust following Apollo conventions |
  50. | `/apollo-skills:skill-creator` | Skill creator — guide for creating new Apollo skills |
  51. ## GitHub CLI
  52. You can also install skills with the [GitHub CLI](https://cli.github.com/) using `gh skill` (preview):
  53. ```bash
  54. # Install skills into the current project for Claude Code
  55. gh skill install apollographql/skills --agent claude-code
  56. # Install at user scope (available everywhere)
  57. gh skill install apollographql/skills --agent claude-code --scope user
  58. # Pin to a specific release (skipped during updates so it won't auto-upgrade)
  59. gh skill install apollographql/skills --pin v1.0.0 --agent claude-code
  60. # Preview skills before installing
  61. gh skill preview apollographql/skills
  62. ```
  63. `--agent` supports many hosts beyond Claude Code (Cursor, Codex, Gemini CLI, GitHub Copilot, and more); run `gh skill install --help` for the full list.
  64. ## Releases
  65. Releases are tagged with semver and published automatically whenever a content change is merged to `main`. The full list lives at [github.com/apollographql/skills/releases](https://github.com/apollographql/skills/releases).
  66. | Install path | What you get |
  67. |---|---|
  68. | `gh skill install apollographql/skills <name>` | Latest tagged release |
  69. | `gh skill install apollographql/skills <name> --pin v1.0.0` | Pinned to a specific release (skipped during updates) |
  70. | `npx skills add apollographql/skills@<name>` | Latest content from `main` (no tag) |
  71. | Claude Code plugin (`claude plugin install`) | Latest plugin version (auto-updates via `claude plugin update`) |
  72. If you need stability, pin via `gh skill install … --pin vX.Y.Z`. Pinned skills are skipped during `gh skill upgrade`, so you upgrade deliberately. For the freshest content, the other paths track `main` HEAD directly.
  73. ## Available Skills
  74. ### graphos-factory
  75. Build and iterate on an Apollo Connectors subgraph for a GraphOS supergraph from a REST API, with or without an OpenAPI or Swagger spec. It works with any agent that can run shell commands (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and others), and replaces the `apollo-connectors` skill. It is developed in [apollographql/graphos-factory](https://github.com/apollographql/graphos-factory); `skills/graphos-factory/` here is a read-only copy of its latest release, updated by that repository's release workflow.
  76. **Install:**
  77. ```bash
  78. npx skills add apollographql/skills@graphos-factory
  79. ```
  80. Or from its own repository, with either CLI:
  81. ```bash
  82. npx skills add apollographql/graphos-factory
  83. gh skill install apollographql/graphos-factory graphos-factory --agent claude-code # or codex, cursor, github-copilot, ...
  84. ```
  85. In Claude Code it is also part of the [`apollo-skills` plugin](#claude-code-plugin), as `/apollo-skills:graphos-factory`. The first time the agent uses it, the skill downloads its `graphos-factory` binary (about 3 MB) from the release it ships with.
  86. **Use when:**
  87. - Wrapping a REST API as a GraphQL subgraph for your supergraph
  88. - Adding or removing operations or fields on an existing connector subgraph
  89. - Refreshing a connector subgraph against a new version of its spec
  90. - Recording live API traffic as test fixtures
  91. **Categories covered:**
  92. - API discovery and spec intake (OpenAPI 3.x, Swagger 2.0, or no spec)
  93. - Operation and field selection, recorded in a dedicated git workspace
  94. - Connectors schema authoring, naming and mapping
  95. - Verification: composition, connector unit tests, mocked end-to-end and live runs
  96. - Design decisions and hand edits kept across regenerations
  97. **Examples:**
  98. - "Turn this REST API into a subgraph for my supergraph"
  99. - "Build a connector subgraph from this OpenAPI spec"
  100. - "Add the list-issues endpoint to my Gitea subgraph"
  101. **References:**
  102. [SKILL.md](skills/graphos-factory/SKILL.md) ·
  103. [README](https://github.com/apollographql/graphos-factory/blob/main/README.md) ·
  104. [Connectors Language](skills/graphos-factory/graphos-factory-core/references/connectors-language.md) ·
  105. [Mapping Language](skills/graphos-factory/graphos-factory-core/references/mapping-language.md) ·
  106. [Schema Authoring](skills/graphos-factory/graphos-factory-core/references/schema-authoring.md) ·
  107. [Testing](skills/graphos-factory/graphos-factory-core/references/testing.md) ·
  108. [Verification](skills/graphos-factory/references/verification.md)
  109. ---
  110. ### apollo-federation
  111. Author Apollo Federation subgraph schemas with entities, sharing, and cross-subgraph field resolution.
  112. **Install:**
  113. ```bash
  114. npx skills add apollographql/skills --skill apollo-federation
  115. ```
  116. **Use when:**
  117. - Creating new subgraph schemas for a federated supergraph
  118. - Defining or modifying entities with `@key`
  119. - Sharing types/fields across subgraphs with `@shareable`
  120. - Working with federation directives (`@external`, `@requires`, `@provides`, `@override`)
  121. - Troubleshooting composition errors
  122. **Categories covered:**
  123. - Entity definition and `@key` patterns (compound, multiple, differing)
  124. - Reference resolvers and computed fields
  125. - Value types with `@shareable`
  126. - Field migration with `@override` (including progressive rollout)
  127. - Entity interfaces with `@interfaceObject`
  128. - Common composition errors and fixes
  129. **Examples:**
  130. - "Create a federated subgraph for my products service"
  131. - "Add a computed field that requires data from another subgraph"
  132. - "Migrate this field from one subgraph to another"
  133. **References:**
  134. [SKILL.md](skills/apollo-federation/SKILL.md) ·
  135. [Directives](skills/apollo-federation/references/directives.md) ·
  136. [Schema Patterns](skills/apollo-federation/references/schema-patterns.md) ·
  137. [Composition](skills/apollo-federation/references/composition.md)
  138. ---
  139. ### apollo-mcp-server
  140. Configure and use Apollo MCP Server to connect AI agents with GraphQL APIs.
  141. **Install:**
  142. ```bash
  143. npx skills add apollographql/skills@apollo-mcp-server
  144. ```
  145. **Use when:**
  146. - Setting up Apollo MCP Server for Claude or other AI agents
  147. - Defining MCP tools from GraphQL operations
  148. - Using introspection tools (introspect, search, validate, execute)
  149. - Troubleshooting MCP server connectivity issues
  150. **Categories covered:**
  151. - Server configuration (endpoints, schemas, headers)
  152. - Built-in tools and compact notation
  153. - Operation sources (files, collections, persisted queries)
  154. - Authentication and security
  155. - Health checks and debugging
  156. **Examples:**
  157. - "Set up Apollo MCP Server for my GraphQL endpoint"
  158. - "Configure MCP tools from my GraphQL operations"
  159. - "Debug MCP server connection issues"
  160. **References:**
  161. [SKILL.md](skills/apollo-mcp-server/SKILL.md) ·
  162. [Tools](skills/apollo-mcp-server/references/tools.md) ·
  163. [Configuration](skills/apollo-mcp-server/references/configuration.md) ·
  164. [Troubleshooting](skills/apollo-mcp-server/references/troubleshooting.md)
  165. ---
  166. ### apollo-router
  167. Configure and run Apollo Router for federated GraphQL supergraphs.
  168. **Install:**
  169. ```bash
  170. npx skills add apollographql/skills@apollo-router
  171. ```
  172. **Use when:**
  173. - Setting up Apollo Router to run a supergraph
  174. - Configuring routing, headers, or CORS
  175. - Implementing custom plugins (Rhai scripts or coprocessors)
  176. - Configuring telemetry and observability
  177. - Troubleshooting Router performance or connectivity issues
  178. **Categories covered:**
  179. - Installation and quick start
  180. - Router configuration (YAML)
  181. - Header propagation and manipulation
  182. - CORS and authentication
  183. - Rhai scripts and coprocessors
  184. - Telemetry (tracing, metrics, logging)
  185. **Examples:**
  186. - "Set up Apollo Router for my supergraph"
  187. - "Configure CORS for my Router"
  188. - "Add header propagation for authentication"
  189. **References:**
  190. [SKILL.md](skills/apollo-router/SKILL.md) ·
  191. [Configuration](skills/apollo-router/references/configuration.md) ·
  192. [Headers](skills/apollo-router/references/headers.md) ·
  193. [Plugins](skills/apollo-router/references/plugins.md) ·
  194. [Telemetry](skills/apollo-router/references/telemetry.md) ·
  195. [Troubleshooting](skills/apollo-router/references/troubleshooting.md)
  196. ---
  197. ### apollo-server
  198. Build GraphQL servers with Apollo Server 4.x, including schemas, resolvers, authentication, and plugins.
  199. **Install:**
  200. ```bash
  201. npx skills add apollographql/skills@apollo-server
  202. ```
  203. **Use when:**
  204. - Setting up a new Apollo Server project
  205. - Writing resolvers or defining GraphQL schemas
  206. - Implementing authentication or authorization
  207. - Creating plugins or custom data sources
  208. - Troubleshooting Apollo Server errors or performance issues
  209. **Categories covered:**
  210. - Quick start setup (standalone and Express)
  211. - Schema definition and type system
  212. - Resolver patterns and best practices
  213. - Context and authentication
  214. - Plugins and lifecycle hooks
  215. - Data sources and DataLoader
  216. - Error handling and formatting
  217. **Examples:**
  218. - "Create an Apollo Server with user authentication"
  219. - "Write resolvers for my GraphQL schema"
  220. - "Add a custom plugin to log all queries"
  221. **References:**
  222. [SKILL.md](skills/apollo-server/SKILL.md) ·
  223. [Resolvers](skills/apollo-server/references/resolvers.md) ·
  224. [Context & Auth](skills/apollo-server/references/context-and-auth.md) ·
  225. [Plugins](skills/apollo-server/references/plugins.md) ·
  226. [Data Sources](skills/apollo-server/references/data-sources.md) ·
  227. [Error Handling](skills/apollo-server/references/error-handling.md) ·
  228. [Troubleshooting](skills/apollo-server/references/troubleshooting.md)
  229. ---
  230. ### apollo-client
  231. Build React applications with Apollo Client 4.x for GraphQL data management, caching, and local state.
  232. **Install:**
  233. ```bash
  234. npx skills add apollographql/skills@apollo-client
  235. ```
  236. **Use when:**
  237. - Setting up Apollo Client in a React project
  238. - Writing GraphQL queries or mutations with hooks
  239. - Configuring caching or cache policies
  240. - Managing local state with reactive variables
  241. - Troubleshooting Apollo Client errors or performance issues
  242. **Categories covered:**
  243. - Quick start setup (install, client, provider, query)
  244. - useQuery and useLazyQuery hooks
  245. - useMutation with optimistic UI
  246. - InMemoryCache and type policies
  247. - Reactive variables and local state
  248. - Error handling and error links
  249. - Performance optimization
  250. **Examples:**
  251. - "Set up Apollo Client in my React app"
  252. - "Implement optimistic UI for my mutation"
  253. - "Configure cache policies for my queries"
  254. **References:**
  255. [SKILL.md](skills/apollo-client/SKILL.md) ·
  256. [Queries](skills/apollo-client/references/queries.md) ·
  257. [Mutations](skills/apollo-client/references/mutations.md) ·
  258. [Caching](skills/apollo-client/references/caching.md) ·
  259. [State Management](skills/apollo-client/references/state-management.md) ·
  260. [Error Handling](skills/apollo-client/references/error-handling.md) ·
  261. [Troubleshooting](skills/apollo-client/references/troubleshooting.md)
  262. ---
  263. ### apollo-ios
  264. Build Apple-platform applications with Apollo iOS, the strongly-typed GraphQL client for Swift (iOS, macOS, tvOS, watchOS, visionOS).
  265. **Install:**
  266. ```bash
  267. npx skills add apollographql/skills@apollo-ios
  268. ```
  269. **Use when:**
  270. - Adding Apollo iOS to a Swift Package Manager or Xcode project
  271. - Configuring `apollo-codegen-config.json` and running code generation
  272. - Configuring an `ApolloClient` with auth, interceptors, and caching
  273. - Writing queries, mutations, or subscriptions from SwiftUI views
  274. - Writing tests against generated operation mocks
  275. **Categories covered:**
  276. - SPM installation, product linking (`Apollo` vs `ApolloAPI`), and `apollo-ios-cli` setup
  277. - Code generation config (`apollo-codegen-config.json`) with the canonical `swiftPackage` + `relative` defaults
  278. - Custom scalars (default `String` typealias, when and how to replace it)
  279. - Queries, mutations, watchers, and cache policies with async/await
  280. - Normalized cache, `@typePolicy` cache keys, manual reads/writes
  281. - Interceptor architecture split across HTTP and GraphQL layers (auth token attachment + token refresh + retry)
  282. - Subscriptions over HTTP multipart and WebSocket, with scene-phase pause/resume
  283. - Testing with `ApolloTestSupport` and generated `Mock<Type>` fixtures (enabled lazily when tests need them)
  284. **Examples:**
  285. - "Set up Apollo iOS in a new SwiftUI app"
  286. - "Add an auth token to every GraphQL request"
  287. - "Subscribe to a GraphQL subscription from a SwiftUI view"
  288. **References:**
  289. [SKILL.md](skills/apollo-ios/SKILL.md) ·
  290. [Setup](skills/apollo-ios/references/setup.md) ·
  291. [Codegen](skills/apollo-ios/references/codegen.md) ·
  292. [Custom Scalars](skills/apollo-ios/references/custom-scalars.md) ·
  293. [Operations](skills/apollo-ios/references/operations.md) ·
  294. [Caching](skills/apollo-ios/references/caching.md) ·
  295. [Interceptors](skills/apollo-ios/references/interceptors.md) ·
  296. [Subscriptions](skills/apollo-ios/references/subscriptions.md) ·
  297. [Testing](skills/apollo-ios/references/testing.md)
  298. ---
  299. ### apollo-kotlin
  300. Build applications with Apollo Kotlin, the GraphQL client library for Android and Kotlin.
  301. **Install:**
  302. ```bash
  303. npx skills add apollographql/skills@apollo-kotlin
  304. ```
  305. **Use when:**
  306. - Setting up Apollo Kotlin in a Gradle project for Android, Kotlin/JVM, or KMP
  307. - Configuring schema download and codegen for GraphQL services
  308. - Configuring an `ApolloClient` with auth, interceptors, and caching
  309. - Writing queries, mutations, or subscriptions
  310. **Categories covered:**
  311. - Gradle plugin setup and service configuration
  312. - Schema management and code generation
  313. - ApolloClient configuration
  314. - Coroutines and Flow usage patterns
  315. - Normalized cache and cache policies
  316. **Examples:**
  317. - "Set up Apollo Kotlin in my Android app"
  318. - "Configure code generation for multiple GraphQL services"
  319. - "Add normalized caching for offline support"
  320. **References:**
  321. [SKILL.md](skills/apollo-kotlin/SKILL.md) ·
  322. [Setup](skills/apollo-kotlin/references/setup.md) ·
  323. [Operations](skills/apollo-kotlin/references/operations.md) ·
  324. [Caching](skills/apollo-kotlin/references/caching.md) ·
  325. ---
  326. ### rover
  327. Manage GraphQL schemas and run local supergraph development with Apollo Rover CLI.
  328. **Install:**
  329. ```bash
  330. npx skills add apollographql/skills@rover
  331. ```
  332. **Use when:**
  333. - Publishing or fetching subgraph schemas to/from GraphOS
  334. - Composing supergraph schemas locally
  335. - Running local supergraph development with rover dev
  336. - Validating schemas with check and lint commands
  337. **Categories covered:**
  338. - Subgraph commands (fetch, publish, check, lint)
  339. - Graph commands (monograph management)
  340. - Supergraph composition
  341. - Local development with rover dev
  342. - Authentication and configuration
  343. **Examples:**
  344. - "Publish my subgraph schema to GraphOS"
  345. - "Run rover dev to test my supergraph locally"
  346. - "Check my schema changes before deploying"
  347. **References:**
  348. [SKILL.md](skills/rover/SKILL.md) ·
  349. [Subgraphs](skills/rover/references/subgraphs.md) ·
  350. [Graphs](skills/rover/references/graphs.md) ·
  351. [Supergraphs](skills/rover/references/supergraphs.md) ·
  352. [Dev](skills/rover/references/dev.md) ·
  353. [Configuration](skills/rover/references/configuration.md)
  354. ---
  355. ### graphql-schema
  356. Design GraphQL schemas following industry best practices for type design, naming, pagination, errors, and security.
  357. **Install:**
  358. ```bash
  359. npx skills add apollographql/skills@graphql-schema
  360. ```
  361. **Use when:**
  362. - Designing a new GraphQL schema or API
  363. - Reviewing existing schema for improvements
  364. - Deciding on type structures or nullability
  365. - Implementing pagination or error patterns
  366. - Ensuring security in schema design
  367. **Categories covered:**
  368. - Type design patterns (interfaces, unions, custom scalars)
  369. - Naming conventions for types, fields, and arguments
  370. - Cursor-based pagination (Connection pattern)
  371. - Error modeling and result types
  372. - Security best practices (depth limiting, complexity, authorization)
  373. **Examples:**
  374. - "Design a GraphQL schema for my e-commerce API"
  375. - "Review my schema for best practices"
  376. - "Add cursor-based pagination to my queries"
  377. **References:**
  378. [SKILL.md](skills/graphql-schema/SKILL.md) ·
  379. [Types](skills/graphql-schema/references/types.md) ·
  380. [Naming](skills/graphql-schema/references/naming.md) ·
  381. [Pagination](skills/graphql-schema/references/pagination.md) ·
  382. [Errors](skills/graphql-schema/references/errors.md) ·
  383. [Security](skills/graphql-schema/references/security.md)
  384. ---
  385. ### graphql-operations
  386. Write GraphQL operations (queries, mutations, fragments) following best practices for client-side development.
  387. **Install:**
  388. ```bash
  389. npx skills add apollographql/skills@graphql-operations
  390. ```
  391. **Use when:**
  392. - Writing GraphQL queries or mutations
  393. - Organizing operations with fragments
  394. - Optimizing data fetching patterns
  395. - Setting up type generation or linting
  396. - Reviewing operations for efficiency
  397. **Categories covered:**
  398. - Query patterns and optimization
  399. - Mutation patterns and error handling
  400. - Fragment organization and colocation
  401. - Variable usage and types
  402. - Tooling (GraphQL Code Generator, ESLint, IDE extensions)
  403. **Examples:**
  404. - "Write a query with pagination"
  405. - "Organize my operations with fragments"
  406. - "Set up GraphQL Code Generator for type safety"
  407. **References:**
  408. [SKILL.md](skills/graphql-operations/SKILL.md) ·
  409. [Queries](skills/graphql-operations/references/queries.md) ·
  410. [Mutations](skills/graphql-operations/references/mutations.md) ·
  411. [Fragments](skills/graphql-operations/references/fragments.md) ·
  412. [Variables](skills/graphql-operations/references/variables.md) ·
  413. [Tooling](skills/graphql-operations/references/tooling.md)
  414. ---
  415. ### rust-best-practices
  416. Write idiomatic Rust code following Apollo GraphQL's best practices handbook.
  417. **Install:**
  418. ```bash
  419. npx skills add apollographql/skills@rust-best-practices
  420. ```
  421. **Use when:**
  422. - Writing new Rust code or functions
  423. - Reviewing or refactoring existing Rust code
  424. - Deciding between borrowing vs cloning or ownership patterns
  425. - Implementing error handling with Result types
  426. - Optimizing Rust code for performance
  427. - Writing tests or documentation for Rust projects
  428. **Categories covered:**
  429. - Coding style and idioms (borrowing, Option/Result, iterators)
  430. - Clippy and linting discipline
  431. - Performance optimization and profiling
  432. - Error handling with thiserror and anyhow
  433. - Testing strategies and snapshot testing
  434. - Generics, static and dynamic dispatch
  435. - Type state pattern for compile-time safety
  436. - Documentation best practices
  437. - Pointer types and thread safety
  438. **Examples:**
  439. - "Review this Rust code for best practices"
  440. - "Help me decide between cloning and borrowing here"
  441. - "Add proper error handling to this function"
  442. **References:**
  443. [SKILL.md](skills/rust-best-practices/SKILL.md) ·
  444. [Style](skills/rust-best-practices/references/style.md) ·
  445. [Errors](skills/rust-best-practices/references/errors.md) ·
  446. [Performance](skills/rust-best-practices/references/performance.md) ·
  447. [Testing](skills/rust-best-practices/references/testing.md) ·
  448. [Advanced](skills/rust-best-practices/references/advanced.md)
  449. ---
  450. ### skill-creator
  451. Guide for creating effective skills for Apollo GraphQL and GraphQL development.
  452. **Install:**
  453. ```bash
  454. npx skills add apollographql/skills@skill-creator
  455. ```
  456. **Use when:**
  457. - Creating a new skill for this repository
  458. - Updating an existing skill's structure or content
  459. - Learning skill best practices and patterns
  460. - Writing SKILL.md files or reference documentation
  461. **Categories covered:**
  462. - SKILL.md format and frontmatter fields
  463. - Directory structure and reference files
  464. - Description writing for agent activation triggers
  465. - Progressive disclosure and context optimization
  466. - Apollo Voice writing style guidelines
  467. - Validation checklist for new skills
  468. **Examples:**
  469. - "Create a new skill for Apollo Federation"
  470. - "Help me write a SKILL.md for my custom skill"
  471. - "Review my skill structure for best practices"
  472. **References:**
  473. [SKILL.md](skills/skill-creator/SKILL.md) ·
  474. [Apollo Skills](skills/skill-creator/references/apollo-skills.md)
  475. ---
  476. ### apollo-connectors
  477. > **Deprecated.** Superseded by [graphos-factory](#graphos-factory) (`npx skills add apollographql/skills@graphos-factory`). This skill will be removed in a future release.
  478. Write Apollo Connectors schemas to integrate REST APIs into GraphQL.
  479. **Install:**
  480. ```bash
  481. npx skills add apollographql/skills@apollo-connectors
  482. ```
  483. ---
  484. ## Usage
  485. Skills activate automatically once installed. The agent uses them when relevant tasks are detected.
  486. You can also explicitly invoke a skill depending on your tool:
  487. | Tool | Automatic | Explicit Invocation |
  488. | -------------- | --------- | ------------------------------------------------------- |
  489. | Claude Code | Yes | Slash command (e.g., `/graphql-schema` or `/apollo-skills:graphql-schema` via plugin) |
  490. | GitHub Copilot | Yes | `/agent` for custom agents, `@github` for GitHub skills |
  491. | Cursor | Yes | Rules matched by file patterns (no direct invocation) |
  492. | Windsurf | Yes | Slash command for workflows (e.g., `/workflow-name`) |
  493. ## Skill Structure
  494. Each skill contains:
  495. - `SKILL.md` - Instructions for the agent (required)
  496. - `references/` - Supporting documentation (optional)
  497. ## Resources
  498. - [Apollo Client Documentation](https://www.apollographql.com/docs/react/)
  499. - [Apollo Server Documentation](https://www.apollographql.com/docs/apollo-server/)
  500. - [Apollo Connectors Documentation](https://www.apollographql.com/docs/graphos/schema-design/connectors/)
  501. - [Apollo Federation Documentation](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/)
  502. - [Apollo MCP Server](https://www.apollographql.com/docs/apollo-mcp-server/)
  503. - [Apollo iOS Documentation](https://www.apollographql.com/docs/ios/)
  504. - [Rover CLI Documentation](https://www.apollographql.com/docs/rover/)
  505. - [Rust Best Practices Handbook](https://github.com/apollographql/rust-best-practices)
  506. ## Disclaimer
  507. The code in this repository is experimental and for reference purposes only. Community feedback is welcome but this project is not officially supported in the same way that repositories in the official [Apollo GraphQL GitHub organization](https://github.com/apollographql) are. If you need help you can file an issue on this repository, [contact Apollo](https://www.apollographql.com/contact-sales) to talk to an expert, or create a ticket directly in Apollo Studio.
skills/graphos-factory/graphos-factory-core/scripts/e2e.sh · Bundled script · 489 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # e2e.sh — WireMock-backed cases through a real Apollo Router.
  3. #
  4. # e2e.sh [workspace-dir] [--generate] [--only PATTERN]
  5. #
  6. # Layer 3, and the only layer where a real router parses the real GraphQL
  7. # documents and sends real HTTP requests. WireMock runs from its standalone
  8. # JAR (Java), and unmatched upstream requests are printed WITH their
  9. # bodies, because "what did the connector actually send?" is the question
  10. # this layer is for.
  11. #
  12. # All-stubs-at-once loading (references/testing.md): every classified mapping
  13. # loads into WireMock once, before the first case runs, and stays loaded for
  14. # the whole suite — every stub is mounted flat, unlike this script's own
  15. # former per-case reset-and-reload. Two stubs whose
  16. # `request` matcher is identical can then only ever be answered by one of
  17. # them, WireMock's own tie-break deciding which; that is a fixture defect
  18. # any flat-mounting runner downstream would also hit, so it must fail here
  19. # first.
  20. # Only the request journal and WireMock's scenario state reset between
  21. # cases (`DELETE $ADMIN/requests`, `POST $ADMIN/scenarios/reset`; neither
  22. # touches loaded mappings), so per-case stub-hit accounting is unaffected
  23. # by every other case's stubs also being loaded. A case whose own stub
  24. # declares a `requiredScenarioState` other than `Started` (references/
  25. # testing.md — a WireMock Scenario, the only way to disambiguate a request
  26. # that is identical by definition, e.g. an operation with no body) has that
  27. # state set directly before its request fires. Every mapping must still be
  28. # classifiable — by `metadata."x-cases"`, by a basename matching a case
  29. # name (hyphens and underscores interchangeable), or by `metadata."x-shared"`
  30. # — or the run fails before any case executes.
  31. # Stub-hit accounting after each case: every upstream request matched a
  32. # loaded stub and at least one was made, unless the .graphql declares
  33. # `# expect-unmatched-upstream`. Every stub that answered must also be the
  34. # case's own (its case list or shared.list): with every stub loaded at once,
  35. # another case's stub can answer a request the connector got wrong (a
  36. # dropped query parameter matching a sibling's `absent` matcher), and that
  37. # must fail the case, as per-case loading did. The request
  38. # journal names the stub that answered each request (`stubMapping.name`,
  39. # the fixture's filename, set at load). A stub of the case's own marked
  40. # `metadata."x-required": true` must also have answered at least one request,
  41. # or the case fails naming it: a $batch case's lookup, which a
  42. # planner that resolves the fields locally never calls.
  43. #
  44. # Upstream status, before the snapshot diff: a case declaring
  45. # `# expect-upstream-status: CODE` fails unless one of its own stubs
  46. # answered CODE. A router that redacts subgraph errors renders every error
  47. # status alike, so the snapshot alone cannot tell a 401 case from a 404 one.
  48. # A case without the directive whose stub answered a non-2xx status, calling
  49. # a root field whose operation documents more than one, reports UNPROVEN:
  50. # counted apart, never as a pass, and not a failure of the run.
  51. #
  52. # --only PATTERN restricts which cases actually run (each is the 3-file unit
  53. # of tests/cases/NAME.graphql, its .expected.json, and its
  54. # mapping) to those whose NAME contains PATTERN as a literal substring,
  55. # hyphens and underscores interchangeable — same normalisation the mapping
  56. # classifier below already uses. Classification still runs over every
  57. # mapping regardless of --only, so a filtered run cannot mask an
  58. # unclassifiable fixture. A PATTERN matching no case fails closed (exit 1)
  59. # before WireMock or the router starts.
  60. #
  61. # Exit 127 = a tool is missing (java, curl, jq): the layer is `skipped` in
  62. # evidence with that reason, never `pass`. Exit 3 = the user has not accepted
  63. # the Elastic License v2 of the composition plugin and the Router
  64. # (APOLLO_ELV2_LICENSE, see elv2.sh): the layer is `not_run` with that
  65. # reason, never `pass`, and no Router is downloaded.
  66. set -euo pipefail
  67. WORKSPACE="."
  68. GENERATE=0
  69. ONLY=""
  70. while [ $# -gt 0 ]; do
  71. case "$1" in
  72. --generate) GENERATE=1; shift ;;
  73. --only)
  74. if [ $# -lt 2 ] || [ -z "$2" ]; then echo "e2e: --only requires a non-empty pattern" >&2; exit 1; fi
  75. ONLY="$2"; shift 2 ;;
  76. *) WORKSPACE="$1"; shift ;;
  77. esac
  78. done
  79. WIREMOCK_VERSION="${WIREMOCK_VERSION:-3.13.2}"
  80. ROUTER_VERSION="${ROUTER_VERSION:-2.17.0}"
  81. WIREMOCK_PORT="${WIREMOCK_PORT:-8080}"
  82. ROUTER_PORT="${ROUTER_PORT:-4000}"
  83. ROUTER_HEALTH_PORT="${ROUTER_HEALTH_PORT:-8088}"
  84. ADMIN="http://localhost:${WIREMOCK_PORT}/__admin"
  85. for tool in java curl jq; do
  86. command -v "$tool" >/dev/null 2>&1 || { echo "e2e: $tool is not installed" >&2; exit 127; }
  87. done
  88. command -v rover >/dev/null 2>&1 || { echo "e2e: rover is not installed" >&2; exit 127; }
  89. # shellcheck source=SCRIPTDIR/cache.sh
  90. . "$(dirname "$0")/cache.sh"
  91. CACHE="$GRAPHOS_FACTORY_CORE_CACHE_DIR"
  92. # The product binary, and a refusal (exit 78) when it is older than
  93. # the version these scripts pin — see resolve-bin.sh for the order and why.
  94. # shellcheck source=SCRIPTDIR/resolve-bin.sh
  95. . "$(dirname "$0")/resolve-bin.sh"
  96. # shellcheck source=SCRIPTDIR/elv2.sh
  97. . "$(dirname "$0")/elv2.sh"
  98. elv2_require e2e
  99. OUT="$(mktemp -d)"
  100. WIREMOCK_PID=""
  101. ROUTER_PID=""
  102. cleanup() {
  103. if [ -n "$ROUTER_PID" ]; then kill "$ROUTER_PID" 2>/dev/null || true; fi
  104. if [ -n "$WIREMOCK_PID" ]; then kill "$WIREMOCK_PID" 2>/dev/null || true; fi
  105. rm -rf "$OUT"
  106. }
  107. trap cleanup EXIT
  108. CASES_DIR="$WORKSPACE/tests/cases"
  109. MAPPINGS_DIR="$WORKSPACE/tests/fixtures/mappings"
  110. [ -f "$WORKSPACE/tests/router.yaml" ] || { echo "e2e: $WORKSPACE/tests/router.yaml is missing" >&2; exit 1; }
  111. shopt -s nullglob
  112. case_files=("$CASES_DIR"/*.graphql)
  113. mappings=("$MAPPINGS_DIR"/*.json)
  114. shopt -u nullglob
  115. # Byte order, never the shell's locale: a glob and `sort` collate
  116. # by LC_COLLATE, and under en_US.UTF-8 `X_minimal.json` sorts before
  117. # `X.json` while under C it sorts after. Stubs load in this order, and
  118. # WireMock answers a request two stubs match with the one loaded last, so
  119. # the locale once decided which stub answered. Only these sorts are pinned:
  120. # exporting LC_ALL=C would reach WireMock's JVM, whose default charset
  121. # before Java 18 follows it.
  122. if [ ${#case_files[@]} -gt 0 ]; then
  123. sorted=(); while IFS= read -r f; do sorted+=("$f"); done < <(printf '%s\n' "${case_files[@]}" | LC_ALL=C sort)
  124. case_files=("${sorted[@]}")
  125. fi
  126. if [ ${#mappings[@]} -gt 0 ]; then
  127. sorted=(); while IFS= read -r f; do sorted+=("$f"); done < <(printf '%s\n' "${mappings[@]}" | LC_ALL=C sort)
  128. mappings=("${sorted[@]}")
  129. fi
  130. [ ${#case_files[@]} -gt 0 ] || { echo "e2e: no tests/cases/*.graphql" >&2; exit 1; }
  131. run_cases=("${case_files[@]}")
  132. if [[ -n "$ONLY" ]]; then
  133. run_cases=()
  134. norm_only="$(printf '%s' "$ONLY" | tr '-' '_')"
  135. for f in "${case_files[@]}"; do
  136. norm_b="$(printf '%s' "$(basename "${f%.graphql}")" | tr '-' '_')"
  137. [[ "$norm_b" == *"$norm_only"* ]] && run_cases+=("$f")
  138. done
  139. if [[ ${#run_cases[@]} -eq 0 ]]; then
  140. echo "e2e: --only '$ONLY' matched no case in $CASES_DIR" >&2
  141. exit 1
  142. fi
  143. fi
  144. for port in "$WIREMOCK_PORT" "$ROUTER_PORT" "$ROUTER_HEALTH_PORT"; do
  145. if curl -s "http://localhost:$port/" >/dev/null 2>&1; then
  146. echo "e2e: port $port is already in use" >&2
  147. exit 1
  148. fi
  149. done
  150. # ── Toolchain: fetch once into the cache ─────────────────────────────────────
  151. mkdir -p "$CACHE"
  152. WIREMOCK_JAR="$CACHE/wiremock-standalone-$WIREMOCK_VERSION.jar"
  153. ROUTER_BIN="$CACHE/router-$ROUTER_VERSION"
  154. if [ ! -f "$WIREMOCK_JAR" ]; then
  155. echo "e2e: downloading WireMock $WIREMOCK_VERSION"
  156. curl -sfL "https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/$WIREMOCK_VERSION/wiremock-standalone-$WIREMOCK_VERSION.jar" -o "$WIREMOCK_JAR"
    • Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
    • Line 164 on GitHub
  157. fi
  158. # The Router is ELv2-licensed too: this download sits after elv2_require.
  159. if [ ! -x "$ROUTER_BIN" ]; then
  160. echo "e2e: downloading Apollo Router $ROUTER_VERSION"
  161. case "$(uname -s)-$(uname -m)" in
  162. Linux-x86_64) platform="x86_64-unknown-linux-gnu" ;;
  163. Linux-aarch64) platform="aarch64-unknown-linux-gnu" ;;
  164. Darwin-arm64) platform="aarch64-apple-darwin" ;;
  165. Darwin-x86_64) platform="x86_64-apple-darwin" ;;
  166. *) echo "e2e: unsupported platform $(uname -s)-$(uname -m)" >&2; exit 127 ;;
  167. esac
  168. curl -sfL "https://github.com/apollographql/router/releases/download/v$ROUTER_VERSION/router-v$ROUTER_VERSION-$platform.tar.gz" \
  169. | tar xzf - -C "$OUT" --strip-components=1 dist/router
  170. mv "$OUT/router" "$ROUTER_BIN"
  171. chmod +x "$ROUTER_BIN"
  172. fi
  173. # ── Classify every mapping before anything starts ────────────────────────────
  174. INDEX="$OUT/index"
  175. mkdir -p "$INDEX"
  176. for q in "${case_files[@]}"; do
  177. b="$(basename "$q" .graphql)"
  178. printf '%s\t%s\n' "$(printf '%s' "$b" | tr '-' '_')" "$b"
  179. done > "$INDEX/cases.tsv"
  180. case_for_name() {
  181. awk -F'\t' -v n="$(printf '%s' "$1" | tr '-' '_')" '$1==n{print $2; exit}' "$INDEX/cases.tsv"
  182. }
  183. unclassified=""
  184. for m in "${mappings[@]}"; do
  185. if jq -e '.persistent == true' "$m" >/dev/null 2>&1; then
  186. echo "e2e: $(basename "$m") sets \"persistent\": true — WireMock would restore it after every reset and it would answer other cases' requests. Remove it." >&2
  187. exit 1
  188. fi
  189. # A scenario's state is set through `PUT $ADMIN/scenarios/<name>/state`,
  190. # and WireMock 3.13.2 does not decode a percent-encoded name there
  191. # (measured: `%20`, `%23`, `%C3%A9` all 404). A name that needs encoding
  192. # could never be set, so refuse it before any case runs.
  193. scenario="$(jq -r '.scenarioName // empty' "$m")"
  194. # `.` and `..` alone are refused too: curl collapses them as path
  195. # dot-segments, so the PUT would never reach the scenario.
  196. if [[ -n "$scenario" && ( ! "$scenario" =~ ^[A-Za-z0-9._~-]+$ || "$scenario" == "." || "$scenario" == ".." ) ]]; then
  197. echo "e2e: $(basename "$m") scenarioName '$scenario' cannot be addressed in WireMock's scenario admin API (it does not decode URL-encoding, and '.' or '..' alone is a path dot-segment) — use only letters, digits, '.', '_', '~' and '-', and not '.' or '..' alone" >&2
  198. exit 1
  199. fi
  200. has_xcases="$(jq -r '(.metadata // {}) | has("x-cases")' "$m")"
  201. xcases="$(jq -r '(.metadata["x-cases"] // [])[]' "$m")"
  202. xshared="$(jq -r '.metadata["x-shared"] // false' "$m")"
  203. if [[ "$has_xcases" == "true" && -z "$xcases" ]]; then
  204. continue # recorded for an operation with no case yet: classified, loaded for nothing
  205. fi
  206. if [[ -n "$xcases" ]]; then
  207. while IFS= read -r c; do
  208. target="$(case_for_name "$c")"
  209. [[ -n "$target" ]] || { echo "e2e: $(basename "$m") metadata.x-cases names unknown case '$c'" >&2; exit 1; }
  210. echo "$m" >> "$INDEX/case-$target.list"
  211. done <<< "$xcases"
  212. elif [[ "$xshared" == "true" ]]; then
  213. echo "$m" >> "$INDEX/shared.list"
  214. else
  215. target="$(case_for_name "$(basename "$m" .json)")"
  216. if [[ -n "$target" ]]; then echo "$m" >> "$INDEX/case-$target.list"; else unclassified="$unclassified $(basename "$m")"; fi
  217. fi
  218. done
  219. if [[ -n "$unclassified" ]]; then
  220. echo "e2e: mappings not classifiable to any case:$unclassified" >&2
  221. echo "e2e: name the file after its case, list cases in metadata.\"x-cases\", or set metadata.\"x-shared\": true" >&2
  222. exit 1
  223. fi
  224. # Every classified mapping (shared plus every case's), once, deduplicated —
  225. # a mapping named in more than one case's `metadata."x-cases"` appears in
  226. # more than one list file but must still load only once.
  227. # A case whose own stub(s) declare `requiredScenarioState` (WireMock
  228. # Scenarios — the only way to answer two byte-identical requests
  229. # differently once every stub loads together) must be run from exactly
  230. # that state; scenarios reset to `Started` before every case, so a case
  231. # needing anything else sets it directly, derived from its own stub's own
  232. # `requiredScenarioState` — no separate case-file declaration exists or is
  233. # needed (references/testing.md).
  234. set_scenario_states() {
  235. local list="$INDEX/case-$1.list" m name state
  236. [[ -f "$list" ]] || return 0
  237. while IFS= read -r m; do
  238. name="$(jq -r '.scenarioName // empty' "$m")"
  239. state="$(jq -r '.requiredScenarioState // empty' "$m")"
  240. if [[ -n "$name" && -n "$state" && "$state" != "Started" ]]; then
  241. # The name is a URL path segment here; it needs no encoding because
  242. # names outside [A-Za-z0-9._~-] are refused before any case runs.
  243. curl -sf -X PUT "$ADMIN/scenarios/$name/state" -H 'Content-Type: application/json' \
  244. -d "$(jq -n --arg s "$state" '{state: $s}')" >/dev/null \
  245. || { echo "e2e: could not set scenario $name to $state" >&2; return 1; }
  246. fi
  247. done < "$list"
  248. }
  249. load_all_stubs() {
  250. curl -sf -X POST "$ADMIN/reset" >/dev/null || return 1
  251. local list m loaded=()
  252. for list in "$INDEX"/shared.list "$INDEX"/case-*.list; do
  253. [[ -f "$list" ]] || continue
  254. while IFS= read -r m; do loaded+=("$m"); done < "$list"
  255. done
  256. while IFS= read -r m; do
  257. [[ -n "$m" ]] || continue
  258. # Name each stub after its file: WireMock echoes `name` in the request
  259. # journal, which is the only stable way to see which fixture answered.
  260. jq -c --arg n "$(basename "$m")" '.name = $n' "$m" \
  261. | curl -sf -X POST "$ADMIN/mappings" -H 'Content-Type: application/json' --data-binary @- >/dev/null \
  262. || { echo "e2e: WireMock rejected stub $m" >&2; return 1; }
  263. done < <(printf '%s\n' "${loaded[@]-}" | LC_ALL=C sort -u)
  264. }
  265. # ── Render, credential, compose ──────────────────────────────────────────────
  266. # The rendered router config carries this run's ports, so two suites can run
  267. # side by side (WIREMOCK_PORT / ROUTER_PORT / ROUTER_HEALTH_PORT) without
  268. # touching the committed tests/router.yaml.
  269. eval "$("$RC" render "$WORKSPACE" --out "$OUT" --wiremock-port "$WIREMOCK_PORT" --router-port "$ROUTER_PORT" --health-port "$ROUTER_HEALTH_PORT")"
  270. [ -n "${ROUTER_CONFIG:-}" ] || { echo "e2e: render produced no ROUTER_CONFIG" >&2; exit 1; }
  271. # Fixtures assert the forwarded credential, so the router must see one. The
  272. # env var name comes from AUTH_EXPR's test_default; the value is fixed so
  273. # fixtures can match `… test-token` exactly.
  274. AUTH_VAR="$("$RC" auth-env "$WORKSPACE")"
  275. if [ -n "$AUTH_VAR" ]; then
  276. # Always the test token, even when the real credential is in the
  277. # environment (CI carries it for the live layer): WireMock's fixtures match
  278. # `… test-token` exactly, and a real secret must never reach a stub server
  279. # or its request log.
  280. export "$AUTH_VAR=test-token"
  281. fi
  282. SUPERGRAPH="$OUT/supergraph.graphql"
  283. NO_COLOR=1 rover supergraph compose --config "$COMPOSE_CONFIG" > "$SUPERGRAPH" 2> "$OUT/compose.err" \
  284. || { cat "$OUT/compose.err" >&2; echo "e2e: compose failed" >&2; exit 1; }
  285. # ── Start WireMock and the router ────────────────────────────────────────────
  286. WM_ROOT="$OUT/wiremock"
  287. mkdir -p "$WM_ROOT/mappings" "$WM_ROOT/__files"
  288. [ -d "$WORKSPACE/tests/fixtures/__files" ] && cp -r "$WORKSPACE/tests/fixtures/__files/." "$WM_ROOT/__files/"
  289. java -jar "$WIREMOCK_JAR" --port "$WIREMOCK_PORT" --root-dir "$WM_ROOT" --disable-banner > "$OUT/wiremock.log" 2>&1 &
  290. WIREMOCK_PID=$!
  291. deadline=$(( $(date +%s) + 30 ))
  292. until curl -sf "$ADMIN/" >/dev/null 2>&1; do
  293. [ "$(date +%s)" -ge "$deadline" ] && { echo "e2e: WireMock did not start"; tail -20 "$OUT/wiremock.log" >&2; exit 1; }
  294. sleep 0.5
  295. done
  296. env -u OTEL_EXPORTER_OTLP_ENDPOINT "$ROUTER_BIN" --supergraph "$SUPERGRAPH" --config "$ROUTER_CONFIG" > "$OUT/router.log" 2>&1 &
  297. ROUTER_PID=$!
  298. # A large supergraph takes the router longer than 30s to load (Databricks:
  299. # 152.6s to healthy); E2E_ROUTER_START_SECONDS raises the wait, the default
  300. # stays 30.
  301. router_wait=${E2E_ROUTER_START_SECONDS:-30}
  302. router_started=$(date +%s)
  303. deadline=$(( router_started + router_wait ))
  304. until curl -sf "http://localhost:${ROUTER_HEALTH_PORT}/health" >/dev/null 2>&1; do
  305. # A router that exits (a bad config, a supergraph it rejects) is not waited
  306. # out to the deadline.
  307. kill -0 "$ROUTER_PID" 2>/dev/null || { echo "e2e: router exited before it reported healthy"; tail -30 "$OUT/router.log" >&2; exit 1; }
  308. [ "$(date +%s)" -ge "$deadline" ] && { echo "e2e: router did not start within ${router_wait}s (set E2E_ROUTER_START_SECONDS to wait longer)"; tail -30 "$OUT/router.log" >&2; exit 1; }
  309. sleep 1
  310. done
  311. echo "e2e: WireMock $WIREMOCK_VERSION (java), Apollo Router $ROUTER_VERSION, $(rover --version | head -1), ${#run_cases[@]} cases"
  312. if [[ -n "$ONLY" ]]; then
  313. echo "e2e: --only '$ONLY' matched ${#run_cases[@]} of ${#case_files[@]} case(s)"
  314. fi
  315. load_all_stubs || { echo "e2e: could not load stubs" >&2; exit 1; }
  316. # One line per included operation, tab-separated, `-` for an empty column:
  317. # root field, the non-2xx statuses it documents, the ones a recorded run
  318. # already exercised (unused here), and the operation key (`get:/repos/{o}`).
  319. ERROR_STATUSES="$("$RC" error-statuses "$WORKSPACE")" || { echo "e2e: could not read the documented error statuses" >&2; exit 1; }
  320. # The statuses the journal shows answering the operation's OWN request: a
  321. # matched entry with the operation's method whose URL path (query dropped)
  322. # ends with its path template, segment by segment, a {parameter} standing
  323. # for exactly one non-empty segment. A status served to any other request
  324. # in the case (a nested lookup, a side call) is not the operation's.
  325. # shellcheck disable=SC2016
  326. OWN_STATUSES_JQ='
  327. def segs: split("/");
  328. def ends_with_template($t):
  329. segs as $p | ($t | ltrimstr("/") | segs) as $q
  330. | ($p | length) >= ($q | length)
  331. and ([range(0; $q | length) as $i
  332. | ($p[($p | length) - ($q | length) + $i]) as $ps
  333. | (if ($q[$i] | test("^\\{.*\\}$")) then ($ps | length) > 0 else $ps == $q[$i] end)]
  334. | all);
  335. [.requests[] | select(.wasMatched)
  336. | select((.request.method | ascii_upcase) == ($m | ascii_upcase))
  337. | select((.request.url | split("?")[0]) | ends_with_template($t))
  338. | .response.status | tostring] | unique | join(",")'
  339. # ── Cases ────────────────────────────────────────────────────────────────────
  340. PASS=0; FAIL=0; UNPROVEN=0
  341. for query_file in "${run_cases[@]}"; do
  342. name="$(basename "${query_file%.graphql}")"
  343. expected="${query_file%.graphql}.expected.json"
  344. # Only the journal and scenario state reset — every stub loaded above
  345. # stays in place for every case: every stub is mounted flat.
  346. if ! curl -sf -X POST "$ADMIN/scenarios/reset" >/dev/null; then echo "FAIL: $name — could not reset scenario state"; FAIL=$((FAIL+1)); continue; fi
  347. if ! curl -sf -X DELETE "$ADMIN/requests" >/dev/null; then echo "FAIL: $name — could not reset the request journal"; FAIL=$((FAIL+1)); continue; fi
  348. if ! set_scenario_states "$name"; then echo "FAIL: $name — could not set its stub's scenario state"; FAIL=$((FAIL+1)); continue; fi
  349. actual="$(curl -sf -X POST "http://localhost:${ROUTER_PORT}/" -H 'Content-Type: application/json' \
  350. -d "$(jq -n --rawfile query "$query_file" '{query: $query}')")" || { echo "FAIL: $name — router request failed"; FAIL=$((FAIL+1)); continue; }
  351. # One read of each journal per case, each guarded, so an admin API that
  352. # fails fails this case with a line saying so instead of aborting the run.
  353. journal="$(curl -sf "$ADMIN/requests")" || { echo "FAIL: $name — could not read the request journal"; FAIL=$((FAIL+1)); continue; }
  354. unmatched_journal="$(curl -sf "$ADMIN/requests/unmatched")" || { echo "FAIL: $name — could not read the unmatched-request journal"; FAIL=$((FAIL+1)); continue; }
  355. unmatched="$(jq '.requests | length' <<< "$unmatched_journal")"
  356. matched="$(jq '[.requests[] | select(.wasMatched)] | length' <<< "$journal")"
  357. if grep -q 'expect-unmatched-upstream' "$query_file"; then
  358. if [[ "$unmatched" == "0" ]]; then echo "FAIL: $name — expected an unmatched upstream request, saw none (matched: $matched)"; FAIL=$((FAIL+1)); continue; fi
  359. else
  360. if [[ "$unmatched" != "0" ]]; then
  361. echo "FAIL: $name — $unmatched upstream request(s) matched no loaded stub:"
  362. jq -r '.requests[] | " \(.method) \(.url)\(if .body != "" then "\n body: \(.body)" else "" end)"' <<< "$unmatched_journal"
  363. FAIL=$((FAIL+1)); continue
  364. fi
  365. if [[ "$matched" == "0" ]]; then echo "FAIL: $name — case made no upstream request (dead stubs?)"; FAIL=$((FAIL+1)); continue; fi
  366. fi
  367. own=""
  368. for list in "$INDEX/shared.list" "$INDEX/case-$name.list"; do
  369. [[ -f "$list" ]] || continue
  370. while IFS= read -r m; do own+="$(basename "$m")"$'\n'; done < "$list"
  371. done
  372. foreign="$(jq -r '.requests[] | select(.wasMatched) | (.stubMapping.name // "<unnamed stub>")' <<< "$journal" \
  373. | while IFS= read -r n; do grep -qxF -- "$n" <<< "$own" || echo "$n"; done | LC_ALL=C sort -u | paste -sd, -)"
  374. if [[ -n "$foreign" ]]; then
  375. echo "FAIL: $name — answered by another case's stub: $foreign (the connector's request matched a fixture this case does not own)"
  376. FAIL=$((FAIL+1)); continue
  377. fi
  378. # A stub of the case's own marked `metadata."x-required": true` must have
  379. # answered at least one request: "some stub matched" cannot tell a $batch
  380. # case whose lookup ran from one the planner resolved without it.
  381. answered="$(jq -r '.requests[] | select(.wasMatched) | (.stubMapping.name // empty)' <<< "$journal" | LC_ALL=C sort -u)"
  382. uncalled=""
  383. if [[ -f "$INDEX/case-$name.list" ]]; then
  384. while IFS= read -r m; do
  385. if jq -e '.metadata["x-required"] == true' "$m" >/dev/null 2>&1 \
  386. && ! grep -qxF -- "$(basename "$m")" <<< "$answered"; then
  387. uncalled="$uncalled $(basename "$m")"
  388. fi
  389. done < "$INDEX/case-$name.list"
  390. fi
  391. if [[ -n "$uncalled" ]]; then
  392. echo "FAIL: $name — required stub(s) never called:$uncalled (metadata.\"x-required\": the case passes only when the router sends that request)"
  393. FAIL=$((FAIL+1)); continue
  394. fi
  395. # Every answering stub is the case's own by now. A status counts for an
  396. # operation only when the journal shows it answering that operation's own
  397. # request: the statuses a nested lookup or side call was served
  398. # belong to no operation under test. `OWN` holds one line per operation
  399. # whose root field the case calls: key, own statuses, documented statuses.
  400. served="$(jq -r '[.requests[] | select(.wasMatched) | .response.status] | unique | map(tostring) | join(",")' <<< "$journal")"
  401. OWN=""
  402. while IFS=$'\t' read -r field statuses _executed opkey; do
  403. [[ -n "$field" && -n "$opkey" ]] || continue
  404. grep -qw -- "$field" "$query_file" || continue
  405. own="$(jq -r --arg m "${opkey%%:*}" --arg t "${opkey#*:}" "$OWN_STATUSES_JQ" <<< "$journal")" \
  406. || { own=""; echo "e2e: could not read $opkey's own statuses from the journal" >&2; }
  407. OWN+="$opkey"$'\t'"${own:--}"$'\t'"$statuses"$'\n'
  408. done <<< "$ERROR_STATUSES"
  409. expect_status="$(sed -n 's/^#[[:space:]]*expect-upstream-status:[[:space:]]*\([0-9][0-9][0-9]\).*/\1/p' "$query_file" | head -1)"
  410. unproven=""
  411. credit=""
  412. if [[ -n "$expect_status" ]]; then
  413. hit=""
  414. while IFS=$'\t' read -r opkey own _documented; do
  415. [[ -n "$opkey" ]] || continue
  416. if grep -qxF -- "$expect_status" <<< "${own//,/$'\n'}"; then hit=1; credit+="$opkey $expect_status"$'\n'; fi
  417. done <<< "$OWN"
  418. if [[ -z "$OWN" ]]; then
  419. # No root field of the case names an included operation: nothing to
  420. # attribute a status to, so the case's own stubs are all there is.
  421. if grep -qxF -- "$expect_status" <<< "${served//,/$'\n'}"; then hit=1; fi
  422. fi
  423. if [[ -z "$hit" ]]; then
  424. answered="$(awk -F'\t' 'NF && $1 != "" {printf "%s answered %s; ", $1, ($2 == "-" ? "nothing" : $2)}' <<< "$OWN")"
  425. echo "FAIL: $name — expected the operation's own request to answer $expect_status (expect-upstream-status); ${answered:-its stubs answered ${served:-nothing}}${served:+(every request in the case: $served)}"
  426. FAIL=$((FAIL+1)); continue
  427. fi
  428. else
  429. while IFS=$'\t' read -r opkey own documented; do
  430. [[ -n "$opkey" && "$own" != "-" ]] || continue
  431. nonok="$(tr ',' '\n' <<< "$own" | grep -E '^[13-9][0-9][0-9]$' | paste -sd, - || true)"
  432. [[ -n "$nonok" ]] || continue
  433. if [[ "$documented" == *,* ]]; then
  434. unproven="$opkey's own request was answered $nonok, and it documents $documented: add \`# expect-upstream-status: CODE\`"
  435. break
  436. fi
  437. for c in ${nonok//,/ }; do credit+="$opkey $c"$'\n'; done
  438. done <<< "$OWN"
  439. [[ -z "$unproven" ]] || credit=""
  440. fi
  441. if [[ "$GENERATE" -eq 1 ]]; then
  442. echo "$actual" | jq -S . > "$expected"
  443. echo "WROTE: $(basename "$expected")"; PASS=$((PASS+1))
  444. [[ -z "$unproven" ]] || echo " unproven: $unproven"
  445. elif [[ ! -f "$expected" ]]; then
  446. echo "FAIL: $name — no expected file (run with --generate, then audit the snapshot)"; FAIL=$((FAIL+1))
  447. elif diff <(echo "$actual" | jq -S .) <(jq -S . "$expected") > /dev/null; then
  448. if [[ -n "$unproven" ]]; then
  449. echo "UNPROVEN: $name — $unproven"; UNPROVEN=$((UNPROVEN+1))
  450. else
  451. echo "PASS: $name"; PASS=$((PASS+1))
  452. # What this passing case proved, for evidence's per-status coverage:
  453. # a status served to an operation's own request, never to a side call.
  454. while read -r opkey code; do
  455. if [[ -n "$opkey" ]]; then echo "SERVED: $name $opkey $code"; fi
  456. done <<< "$credit"
  457. fi
  458. else
  459. echo "FAIL: $name"; diff <(echo "$actual" | jq -S .) <(jq -S . "$expected") || true; FAIL=$((FAIL+1))
  460. fi
  461. done
  462. if [[ "$GENERATE" -eq 1 ]]; then
  463. echo "e2e: $PASS expected files written, $FAIL failed — audit every snapshot for \"redacted\", \"valueCompletion\" and errors before committing"
  464. else
  465. echo "e2e: $PASS passed, $FAIL failed$([[ "$UNPROVEN" -eq 0 ]] || echo ", $UNPROVEN unproven")"
  466. fi
  467. [ "$FAIL" -eq 0 ]
skills/graphos-factory/graphos-factory-core/scripts/toolchain.sh · Bundled script · 147 lines · 2 findings marked
  1. #!/usr/bin/env bash
  2. # toolchain.sh — install the tools the validation layers shell out to.
  3. #
  4. # toolchain.sh # rover + the pinned supergraph plugin, Apollo Router, WireMock
  5. # toolchain.sh --check # exit 0 if all four are present at the pinned versions, 1 otherwise
  6. #
  7. # The supergraph plugin and the Apollo Router are licensed under the Elastic
  8. # License v2, which only the user can accept: read it, then set
  9. # APOLLO_ELV2_LICENSE=accept (see elv2.sh). This script never sets it. Unset,
  10. # it installs rover and WireMock, downloads neither the plugin nor the
  11. # Router, says so, and exits 0; compose, unit, e2e and live then report
  12. # `not_run` until the variable is set. --check reports a missing plugin or
  13. # Router with the same instruction (exit 1), and both present with the
  14. # variable unset as a note (exit 0: the tools are installed).
  15. #
  16. # One source of truth for the pins and their install paths; the SessionStart
  17. # hook and CI both call this instead of carrying their own copy:
  18. # rover $ROVER_VERSION + supergraph-v$FEDERATION_VERSION -> $HOME/.rover/bin (compose.sh, unit.sh, e2e.sh, live.sh)
  19. # router-$ROUTER_VERSION -> $GRAPHOS_FACTORY_CORE_CACHE (e2e.sh, live.sh)
  20. # wiremock-standalone-$WIREMOCK_VERSION.jar -> $GRAPHOS_FACTORY_CORE_CACHE (e2e.sh)
  21. # FEDERATION_VERSION must match pilots/*/*/.factory/workspace.yaml; ROUTER_VERSION
  22. # and WIREMOCK_VERSION must match the defaults in e2e.sh and live.sh.
  23. #
  24. # Java is not installed here: e2e.sh and live.sh need it, but every host this
  25. # runs on (the web container, CI's setup-java) already provides it. The
  26. # product binary is bootstrap.sh's job. $GRAPHOS_FACTORY_CORE_CACHE defaults as cache.sh
  27. # says.
  28. #
  29. # Idempotent: every step is skipped when its version is already in place.
  30. # Exit codes: 0 installed · 1 a download failed · 127 no router build for this platform.
  31. set -euo pipefail
  32. ROVER_VERSION="${ROVER_VERSION:-0.41.0}"
  33. FEDERATION_VERSION="${FEDERATION_VERSION:-2.15.2}"
  34. ROUTER_VERSION="${ROUTER_VERSION:-2.17.0}"
  35. WIREMOCK_VERSION="${WIREMOCK_VERSION:-3.13.2}"
  36. # shellcheck source=SCRIPTDIR/cache.sh
  37. . "$(dirname "$0")/cache.sh"
  38. CACHE="$GRAPHOS_FACTORY_CORE_CACHE_DIR"
  39. ROVER_BIN="$HOME/.rover/bin"
  40. ROUTER="$CACHE/router-$ROUTER_VERSION"
  41. WIREMOCK_JAR="$CACHE/wiremock-standalone-$WIREMOCK_VERSION.jar"
  42. export PATH="$ROVER_BIN:$PATH"
  43. # shellcheck source=SCRIPTDIR/elv2.sh
  44. . "$(dirname "$0")/elv2.sh"
  45. MODE="install"
  46. for arg in "$@"; do
  47. case "$arg" in
  48. --check) MODE="check" ;;
  49. -h|--help) sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
  50. *) echo "toolchain: unknown argument $arg" >&2; exit 1 ;;
  51. esac
  52. done
  53. have_rover() { [ "$("$ROVER_BIN/rover" --version 2>/dev/null || true)" = "Rover $ROVER_VERSION" ]; }
  54. have_plugin() { [ -x "$ROVER_BIN/supergraph-v$FEDERATION_VERSION" ]; }
  55. have_router() { [ -x "$ROUTER" ]; }
  56. have_wiremock() { [ -f "$WIREMOCK_JAR" ]; }
  57. router_platform() {
  58. case "$(uname -s)-$(uname -m)" in
  59. Linux-x86_64) echo "x86_64-unknown-linux-gnu" ;;
  60. Linux-aarch64) echo "aarch64-unknown-linux-gnu" ;;
  61. Darwin-x86_64) echo "x86_64-apple-darwin" ;;
  62. Darwin-arm64) echo "aarch64-apple-darwin" ;;
  63. *) echo "" ;;
  64. esac
  65. }
  66. if [ "$MODE" = "check" ]; then
  67. missing=0
  68. have_rover || { echo "toolchain: rover $ROVER_VERSION is not at $ROVER_BIN" >&2; missing=1; }
  69. # The two ELv2-licensed pieces: a missing one fails, and the instruction
  70. # is printed once when the user has not accepted.
  71. elv2_missing=0
  72. have_plugin || { echo "toolchain: supergraph plugin v$FEDERATION_VERSION is not at $ROVER_BIN" >&2; missing=1; elv2_missing=1; }
  73. have_router || { echo "toolchain: Apollo Router $ROUTER_VERSION is not at $ROUTER" >&2; missing=1; elv2_missing=1; }
  74. have_wiremock || { echo "toolchain: WireMock $WIREMOCK_VERSION is not at $WIREMOCK_JAR" >&2; missing=1; }
  75. if ! elv2_accepted; then
  76. [ "$elv2_missing" -eq 1 ] \
  77. || echo "toolchain: note — the supergraph plugin and the Apollo Router are installed, but APOLLO_ELV2_LICENSE is not set to accept" >&2
  78. elv2_explain toolchain
  79. fi
  80. [ "$missing" -eq 0 ] && echo "toolchain: rover $ROVER_VERSION, supergraph v$FEDERATION_VERSION, router $ROUTER_VERSION, wiremock $WIREMOCK_VERSION present"
  81. exit "$missing"
  82. fi
  83. # ── rover + composition plugin ───────────────────────────────────────────────
  84. if have_rover; then
  85. echo "rover $ROVER_VERSION already installed"
  86. else
  87. echo "installing rover $ROVER_VERSION"
  88. curl -fsSL "https://rover.apollo.dev/nix/v${ROVER_VERSION}" | sh -s -- --force
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 94 on GitHub
  89. fi
  90. # What the user's missing ELv2 acceptance held back, explained once at the end.
  91. held=""
  92. plugin="supergraph v$FEDERATION_VERSION"
  93. if have_plugin; then
  94. echo "supergraph plugin v$FEDERATION_VERSION already installed"
  95. elif elv2_accepted; then
  96. # rover reads the user's own APOLLO_ELV2_LICENSE=accept; no flag here.
  97. echo "installing supergraph plugin v$FEDERATION_VERSION"
  98. "$ROVER_BIN/rover" install --plugin "supergraph@=$FEDERATION_VERSION"
  99. else
  100. held="supergraph plugin v$FEDERATION_VERSION"
  101. plugin="no supergraph plugin"
  102. fi
  103. # ── router + WireMock for the e2e and live layers ────────────────────────────
  104. mkdir -p "$CACHE"
  105. router="router $ROUTER_VERSION"
  106. if have_router; then
  107. echo "router $ROUTER_VERSION already cached"
  108. elif ! elv2_accepted; then
  109. held="${held:+$held and the }Apollo Router $ROUTER_VERSION"
  110. router="no router"
  111. else
  112. platform="$(router_platform)"
  113. if [ -z "$platform" ]; then
  114. echo "toolchain: no Apollo Router build for $(uname -s)-$(uname -m); e2e.sh and live.sh will report it as skipped" >&2
  115. exit 127
  116. fi
  117. echo "caching Apollo Router $ROUTER_VERSION ($platform)"
  118. tmp="$(mktemp -d)"
  119. trap 'rm -rf "$tmp"' EXIT
  120. curl -fsSL "https://github.com/apollographql/router/releases/download/v${ROUTER_VERSION}/router-v${ROUTER_VERSION}-${platform}.tar.gz" \
  121. | tar xzf - -C "$tmp" --strip-components=1 dist/router
  122. mv "$tmp/router" "$ROUTER" && chmod +x "$ROUTER"
  123. fi
  124. if have_wiremock; then
  125. echo "WireMock $WIREMOCK_VERSION already cached"
  126. else
  127. echo "caching WireMock $WIREMOCK_VERSION"
  128. curl -fsSL "https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/${WIREMOCK_VERSION}/wiremock-standalone-${WIREMOCK_VERSION}.jar" \
    • Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
    • Line 137 on GitHub
  129. -o "$WIREMOCK_JAR"
  130. fi
  131. note=""
  132. if [ -n "$held" ]; then
  133. echo "toolchain: not downloading the $held" >&2
  134. elv2_explain toolchain
  135. note=" (APOLLO_ELV2_LICENSE not set to accept)"
  136. fi
  137. echo "toolchain: rover $ROVER_VERSION, $plugin, $router, wiremock $WIREMOCK_VERSION ready$note"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.