DOCSEARCHbyAlgolia
Submit Docs

Tailcall Documentation

repository·main·Indexed 23 days ago

https://github.com/tailcallhq/tailcall

An open-source, high-performance solution for building GraphQL backends. Tailcall allows developers to orchestrate APIs by defining GraphQL schemas and resolution logic, such as mapping to REST endpoints, directly within .graphql files using specialized directives like @server and @http, eliminating the need for manual resolver code.

Tokens
14.1K
Snippets
19
Records
101
Agent score
80%

What's inside Tailcall

  2. Build Tailcall WASM for Node.js or Browser

    main

    If you are developing or testing the tailcall-wasm package locally, you can use the following npm scripts within the tailcall-wasm directory:

    Node.js Builds

    • Debug mode: npm run "dev-node" (outputs to node/ folder)
    • Release mode: npm run "build-release-node" (optimized, outputs to node/ folder)

    Browser Builds

    • Debug mode: npm run "dev-browser" (outputs to browser/ folder)
    • Release mode: npm run "build-release-browser" (optimized, outputs to browser/ folder)
    # For Node.js
npm run "dev-node"
npm run "build-release-node"

# For Browser
npm run "dev-browser"
npm run "build-release-browser"

  4. Get Started with Tailcall GraphQL

    main

    Tailcall allows you to build GraphQL backends by defining the schema and its resolution logic (via @server and @http directives) within a single .graphql file. This eliminates the need to write manual resolver code.

    1. Create a .graphql file defining your schema and using @http to map fields to upstream REST endpoints.
    2. Use the tailcall start command to run the server using that file.
    schema @server(port: 8000, hostname: "0.0.0.0") @upstream(httpCache: 42) {
  query: Query
}

type Query {
  posts: [Post] @http(url: "http://jsonplaceholder.typicode.com/posts")
  user(id: Int!): User @http(url: "http://jsonplaceholder.typicode.com/users/{{.args.id}}")
}

type User {
  id: Int!
  name: String!
  username: String!
  email: String!
  phone: String
  website: String
}

type Post {
  id: Int!
  userId: Int!
  title: String!
  body: String!
  user: User @http(url: "http://jsonplaceholder.typicode.com/users/{{.value.userId}}")
}
    tailcall start ./jsonplaceholder.graphql

  5. Run the Sample gRPC Rust News Server

    main

    To start the gRPC-based Rust server which implements CRUD operations and batched news retrieval, use the standard cargo run command from the package directory.

    This server provides:

    • CRUD Operations: Create, Read, Update, and Delete news items.
    • Batched News Retrieval: A GetNews API for fetching multiple news items in a single request.
    • gRPC Interface: Modern protocol for inter-service communication.
    cargo run

  6. Install Tailcall

    main

    You can install Tailcall using several package managers or via direct download scripts and Docker.

    ### NPM
```bash
npm i -g @tailcallhq/tailcall

    Yarn

    yarn global add @tailcallhq/tailcall

    Home Brew

    brew tap tailcallhq/tailcall
brew install tailcall

    Curl

    curl -sSL https://raw.githubusercontent.com/tailcallhq/tailcall/master/install.sh | bash

    Docker

    docker pull ghcr.io/tailcallhq/tailcall/tc-server
docker run -p 8080:8080 -p 8081:8081 ghcr.io/tailcallhq/tailcall/tc-server

  7. Generate gRPC binary files for fixtures

    main

    If you need to update or generate new gRPC binary files for use in fixtures, follow these steps:

    1. Navigate to src/core/proto_reader/fetch.rs.
    2. Modify the GrpcReflection.execute function to print the request body as a string and the response body as a base64 encoded string.
    3. Convert the base64 encoded strings into .bin files using an online base64-to-file converter or manual tools.
    4. Rename the resulting files and replace the existing fixture files in the repository.

  8. Run the Apollo Federation example

    main

    This example demonstrates how to use Tailcall with Apollo Federation by running multiple subgraphs and an Apollo router.

    1. Start Tailcall subgraphs

    Run the following commands to start the subgraph examples:

    cargo run -- start examples/apollo_federation_subgraph_post.graphql
cargo run -- start examples/apollo_federation_subgraph_user.graphql

    2. Run the Apollo router

    You can run the router using one of these two methods:

    Method A: Using @apollo/gateway Navigate to the examples/federation folder and run:

    npm install
npm start

    Method B: Using Apollo Rover If you have Apollo Rover installed, use the rover.sh script.

    3. Access the Supergraph

    Once the subgraphs and router are running, navigate to http://localhost:4000 to execute supergraph queries.

  9. How discriminators resolve GraphQL types

    main

    In Tailcall, a Discriminator is used to determine the type of an object in a GraphQL schema, specifically for resolving the __typename field of Union and Interface types.

    There are two strategies for discrimination:

    1. KeyedDiscriminator: Determines the type based on the presence of specific keys within an object.
    2. TypeFieldDiscriminator: Determines the type by inspecting the value of a specific field (e.g., a type or kind field) within the object.

    Discriminators can be applied to single objects or lists of objects. When resolve_type is called, it inspects the input Value, determines the correct type, and inserts the __typename field into the object. If __typename is already present, the discriminator skips processing to avoid overwriting existing data.

  10. Identify auto-generated type names

    main

    In Tailcall, type names are considered auto-generated if they start with the internal PREFIX (typically GEN__). The InferTypeName::is_auto_generated logic is used to determine which types are candidates for renaming via the LLM inference process.

    Existing user-defined types (those not starting with the prefix) are used as a blacklist to ensure the LLM does not suggest a name that is already in use.

  11. Manage SSL verification in `upstream`

    main

    The verifySSL field (serialized as verifySSL) determines whether Tailcall verifies the upstream server's certificates.

    Warning: Setting verifySSL: false allows self-signed certificates and should only be used during development or testing. In production, it is highly recommended to keep this enabled (true).

  12. Supported Input Sources for the Generator

    main

    When defining inputs in your Tailcall configuration file, you can use the following source types:

    • Curl: Simulates a curl request. Requires src (URL), method, and optionally headers, body, and is_mutation.
    • Proto: Uses Protocol Buffer definitions. Requires src (path to proto file), url, and optionally proto_paths and connect_rpc.
    • Config: Reads from an existing configuration file. Requires src (path to the file).