diff --git a/404.html b/404.html index e013739a2c..9347ed929b 100644 --- a/404.html +++ b/404.html @@ -16,8 +16,8 @@ - - + +
Skip to main content

Logging

Logging acts as an essential tool for obtaining insights into code execution and addressing software development challenges. You can configure the verbosity of logs via log levels. Use TAILCALL_LOG_LEVEL or TC_LOG_LEVEL environment variables to set the application's log level. The available log levels include:

error​

This is the highest severity level. It indicates a critical issue that may lead to the failure of the program or a part of it.

TAILCALL_LOG_LEVEL=error tailcall <COMMAND>
# or
TC_LOG_LEVEL=error tailcall <COMMAND>
diff --git a/docs/guides/n+1/index.html b/docs/guides/n+1/index.html index f686ea4287..87f5ad1af7 100644 --- a/docs/guides/n+1/index.html +++ b/docs/guides/n+1/index.html @@ -16,14 +16,14 @@ - - + +

Tackling N + 1

The N+1 problem is a pervasive and critical issue in application development that occurs when an application ends up issuing a large number of downstream requests, for a single request from upstream. Let's understand with an example:

+ Star

Tackling N + 1

The N+1 problem is a pervasive and critical issue in application development that occurs when an application ends up issuing a large number of downstream requests, for a single request from upstream. Let's understand with an example:

Scenario​

Consider we're developing a feature that involves consuming data from the JSON Placeholder API. The feature requires fetching posts and the details of the authors of these posts.

Here's an illustration of a typical implementation:

@@ -65,6 +65,6 @@

groupBy: ["id"]: This parameter instructs the system to convert the list of responses into a map internally, using the user's id as the unique key. In essence, it allows the system to differentiate each user value in the response list.

-

By using this approach, you can reduce the number of requests from 101 (for 100 posts plus one initial request for the post list) down to 2. This significant optimization effectively handles the N+1 problem, thereby enhancing your application's efficiency and user experience.

+

By using this approach, you can reduce the number of requests from 101 (for 100 posts plus one initial request for the post list) down to 2. This significant optimization effectively handles the N+1 problem, thereby enhancing your application's efficiency and user experience.

\ No newline at end of file diff --git a/docs/guides/tailcall-on-aws/index.html b/docs/guides/tailcall-on-aws/index.html new file mode 100644 index 0000000000..18f7bd26cd --- /dev/null +++ b/docs/guides/tailcall-on-aws/index.html @@ -0,0 +1,41 @@ + + + + + +Tailcall on AWS | Tailcall + + + + + + + + + + + + + + + + +
Skip to main content

Tailcall on AWS

Tailcall can be hosted on AWS using Lambda and API Gateway using the tailcall-on-aws template.

+
    +
  1. Install Terraform. The template uses Terraform to orchestrate the required AWS infrastructure, to spare you the time of setting it up by hand.
    2. +
  2. Set the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION environment variables. These are required by Terraform to be able to manage the resourced on AWS. More info here.
    3. +
  3. Create a new repository using the tailcall-on-aws template.
    4. +
  4. Clone your new repository, run terraform init, and then terraform apply.
    5. +
  5. Done! The API Gateway URL will be logged to the console when you run terraform apply.
    6. +
+

Once you've deployed Tailcall for the first time, you can edit config/config.graphql to build your API. If you install Tailcall locally, you can test your config by running:

+
tailcall start ./config/config.graphql
+

When you want to push your changes to the deployment, you should run terraform apply again. This will also update Tailcall to the latest version.

+

Logging​

+

All Tailcall logs will be uploaded to and stored in AWS CloudWatch. Logs of all levels are stored by default, so that you can filter the logs as necessary when viewing them in CloudWatch.

+

If you would like to filter the logs before they get ingested, you can create the config/.env file and specify the minimum log level with the LOG_LEVEL environment variable. The available levels are: TRACE (default), DEBUG, INFO, WARN and ERROR.

+ + \ No newline at end of file diff --git a/docs/guides/watch-mode/index.html b/docs/guides/watch-mode/index.html index dc344c007b..5f5261ce41 100644 --- a/docs/guides/watch-mode/index.html +++ b/docs/guides/watch-mode/index.html @@ -16,14 +16,14 @@ - - + +
Skip to main content

Watch Mode

Developers often find themselves in situations where they need to run a server in watch mode to streamline the development process. This guide will introduce you to entr, a versatile file-watcher tool, and how to run your server in watch mode with it. We'll also touch on the installation process and suggest some best practices to optimize your workflow.

+ Star

Watch Mode

Developers often find themselves in situations where they need to run a server in watch mode to streamline the development process. This guide will introduce you to entr, a versatile file-watcher tool, and how to run your server in watch mode with it. We'll also touch on the installation process and suggest some best practices to optimize your workflow.

Use case​

Running a server in watch mode offers a lot of key benefits:

    @@ -132,6 +132,6 @@

    So

    Update entr: Ensure entr is always updated to the latest version for bug fixes and enhancements.

    -

    By following these best practices and using entr effectively, you can greatly improve your development workflow. Experiment with entr, adapt it to your project's specific requirements, and enjoy a smoother and more efficient development process. Happy coding!

+

By following these best practices and using entr effectively, you can greatly improve your development workflow. Experiment with entr, adapt it to your project's specific requirements, and enjoy a smoother and more efficient development process. Happy coding!

\ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 7d8318a9d5..2703c7178b 100644 --- a/docs/index.html +++ b/docs/index.html @@ -16,14 +16,14 @@ - - + +
Skip to main content

Introduction

Good APIs craft a broad spectrum of functionalities. Yet, the broader their scope, the more they diverge from being the perfect fit for any specific use case. This fundamental discrepancy — the impedance mismatch between the general capabilities of an API and the precise needs of a particular scenario — amplifies the necessity for an orchestration layer. Such a layer adeptly bridges this gap, tailor-fitting generic APIs to meet exact requirements with finesse. Tailcall stands at the forefront of this innovation, seamlessly transforming the way APIs are integrated and interacted with.

+ Star

Introduction

Good APIs craft a broad spectrum of functionalities. Yet, the broader their scope, the more they diverge from being the perfect fit for any specific use case. This fundamental discrepancy — the impedance mismatch between the general capabilities of an API and the precise needs of a particular scenario — amplifies the necessity for an orchestration layer. Such a layer adeptly bridges this gap, tailor-fitting generic APIs to meet exact requirements with finesse. Tailcall stands at the forefront of this innovation, seamlessly transforming the way APIs are integrated and interacted with.

Tailcall introduces a robust DSL (Domain-Specific Language), enabling developers to fine-tune how APIs are orchestrated. This DSL facilitates specifying different caching and batching strategies to enhance the system's efficiency. It also enables precise governance and access control mechanisms. Tailcall serves as a central hub for team collaboration, offering a unified point for managing all APIs, documentation, and more. Once configured, it positions itself between the clients and microservices, adeptly managing all requests and orchestrating them as needed.

Architecture Diagram

Manually crafting BFF (Backend for Frontend) layers has become outdated. With Tailcall, API orchestration evolves into a streamlined and highly optimized process. It functions as an essential intermediary, intelligently directing requests and assembling responses from each microservice. This approach diminishes the development burden associated with traditional BFF layers but also bolsters performance, reliability, and scalability throughout the application infrastructure.

diff --git a/docs/operators/add-field/index.html b/docs/operators/add-field/index.html index 02f3188d14..e7752abb02 100644 --- a/docs/operators/add-field/index.html +++ b/docs/operators/add-field/index.html @@ -16,14 +16,14 @@ - - + +

@addField

The @addField operator simplifies data structures and queries by adding a field that inline or flattens a nested field or node within your schema. It modifies the schema and the data transformation process, making nested data more accessible and straightforward to present.

+ Star

@addField

The @addField operator simplifies data structures and queries by adding a field that inline or flattens a nested field or node within your schema. It modifies the schema and the data transformation process, making nested data more accessible and straightforward to present.

For instance, consider a schema:

schema {
  query: Query
}

type User @addField(name: "street", path: ["address", "street"]) {
  id: Int!
  name: String!
  username: String!
  email: String!
  phone: String
  website: String
  address: Address @modify(omit: true)
}

type Address {
  street: String!
  city: String!
  state: String!
}

type Query {
  user(id: Int!): User @http(path: "/users/{{args.id}}")
}

Suppose we focus on the street field in Address.

diff --git a/docs/operators/cache/index.html b/docs/operators/cache/index.html index 73ffb93d73..57fdaf8493 100644 --- a/docs/operators/cache/index.html +++ b/docs/operators/cache/index.html @@ -16,14 +16,14 @@ - - + +

@cache

The @cache directive provides a protocol agnostic mechanism for caching the results of fields within a GraphQL schema. Like any other cache implementation, this feature is useful for optimizing performance by reducing the need to fetch data that doesn't change frequently.

+ Star

@cache

The @cache directive provides a protocol agnostic mechanism for caching the results of fields within a GraphQL schema. Like any other cache implementation, this feature is useful for optimizing performance by reducing the need to fetch data that doesn't change frequently.

maxAge​

@cache(maxAge: Int)

This parameter is a non-zero unsigned integer specifying the duration, in milliseconds, that retains the cached value.

diff --git a/docs/operators/call/index.html b/docs/operators/call/index.html index 88ff9a9d63..9e6fbd5cd5 100644 --- a/docs/operators/call/index.html +++ b/docs/operators/call/index.html @@ -16,14 +16,14 @@ - - + +

@call

The @call directive in GraphQL signifies a paradigm shift towards more efficient code structuring by introducing a methodology akin to function invocations in conventional programming. This directive is pivotal for developers navigating the intricacies of elaborate GraphQL schemas, where minimizing redundancy and adhering to the DRY (Don't Repeat Yourself) principle are paramount. Consider the following schema example:

+ Star

@call

The @call directive in GraphQL signifies a paradigm shift towards more efficient code structuring by introducing a methodology akin to function invocations in conventional programming. This directive is pivotal for developers navigating the intricacies of elaborate GraphQL schemas, where minimizing redundancy and adhering to the DRY (Don't Repeat Yourself) principle are paramount. Consider the following schema example:

schema @upstream(baseURL: "https://jsonplaceholder.typicode.com") {
  query: Query
}

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

type Post {
  id: Int!
  userId: Int!
  title: String!
  body: String!
  user: User @http(path: "/users/{{value.userId}}")
}

type User {
  id: Int!
  name: String!
  email: String!
}

In this schema, at lines 7 and 18, a pattern of configuration duplication emerges when fetching user's data by it's id, demonstrating a prime use case for the @call directive. Through refactoring the Post type to incorporate the @call directive, we can eliminate this redundancy.

type Post {
  id: Int!
  userId: Int!
  title: String!
  body: String!
  user: User @call(query: "user", args: {id: "{{value.userId}}"})
}
diff --git a/docs/operators/const/index.html b/docs/operators/const/index.html index 5acdd125b5..9820735de1 100644 --- a/docs/operators/const/index.html +++ b/docs/operators/const/index.html @@ -16,14 +16,14 @@ - - + +

@const

The @const directive in GraphQL is a powerful tool for embedding data directly into your schema, offering two primary functionalities:

+ Star

@const

The @const directive in GraphQL is a powerful tool for embedding data directly into your schema, offering two primary functionalities:

Static​

This feature allows for the inclusion of a constant response within the schema definition itself. It is useful for scenarios where the response is unchanging. e.g:

schema {
  query: Query
}

type Query {
  user: User @const(data: {name: "John", age: 12})
}

type User {
  name: String
  age: Int
}
diff --git a/docs/operators/graphql/index.html b/docs/operators/graphql/index.html index 06c21bd129..932d56b0b2 100644 --- a/docs/operators/graphql/index.html +++ b/docs/operators/graphql/index.html @@ -16,14 +16,14 @@ - - + +

@graphQL

The @graphQL operator allows to specify GraphQL API server request to fetch data from.

+ Star

@graphQL

The @graphQL operator allows to specify GraphQL API server request to fetch data from.

type Query {
  users: [User] @graphQL(name: "userList")
}

The @graphQL operator facilitates fetching a list of users from the GraphQL API upstream. The name argument specifies the root field's name on the upstream server. The upcoming request to the Tailcall server determines the User type's inner fields for the request. Depending on the operation type within which one finds the @graphQL operator, the Tailcall config determines the query's operation type.

For the next request with the config above:

diff --git a/docs/operators/grpc/index.html b/docs/operators/grpc/index.html index a851d9470a..d0d3aa1a7c 100644 --- a/docs/operators/grpc/index.html +++ b/docs/operators/grpc/index.html @@ -16,14 +16,14 @@ - - + +

@grpc

The @grpc directive enables the resolution of GraphQL fields via gRPC services. Below is an illustrative example of how to apply this directive within a GraphQL schema:

+ Star

@grpc

The @grpc directive enables the resolution of GraphQL fields via gRPC services. Below is an illustrative example of how to apply this directive within a GraphQL schema:

schema @link(src: "./users.proto", type: Protobuf) {
  query: Query
}

type Query {
  users: [User] @grpc(method: "users.UserService.ListUsers")
}

This schema snippet demonstrates the directive's application, where a query for users triggers a gRPC request to the UserService's ListUsers method, thereby fetching the user data.

The .proto file delineates the structure and methods of the gRPC service. A simplified example of such a file is as follows:

diff --git a/docs/operators/http/index.html b/docs/operators/http/index.html index 94a5d1d002..5c8a696f20 100644 --- a/docs/operators/http/index.html +++ b/docs/operators/http/index.html @@ -16,14 +16,14 @@ - - + +

@http

The @http operator indicates a field or node relies on a REST API. For example:

+ Star

@http

The @http operator indicates a field or node relies on a REST API. For example:

type Query {
  users: [User] @http(path: "/users")
}

In this example, adding the @http operator to the users field of the Query type indicates reliance on a REST API for the users field. The path argument specifies the REST API's path, which is /users in this scenario.Querying the users field prompts the GraphQL server to issue a GET request to https://jsonplaceholder.typicode.com/users.

baseURL​

diff --git a/docs/operators/index.html b/docs/operators/index.html index c27e2a7d8a..d53383e0ba 100644 --- a/docs/operators/index.html +++ b/docs/operators/index.html @@ -16,14 +16,14 @@ - - + +

Operators

Tailcall DSL builds on your existing GraphQL knowledge by allowing the addition of some custom operators. These operators provide powerful compile time guarantees to ensure your API composition is tight and robust. The system automatically generates highly optimized resolver logic for your types using the operator information.

+ Star

Operators

Tailcall DSL builds on your existing GraphQL knowledge by allowing the addition of some custom operators. These operators provide powerful compile time guarantees to ensure your API composition is tight and robust. The system automatically generates highly optimized resolver logic for your types using the operator information.

Here is a list of all the custom operators supported by Tailcall:

Certainly! Here's the table with hyperlinks added back to the operator names:

OperatorDescription
@addFieldSimplifies data structures and queries by adding, inlining, or flattening fields or nodes within the schema.
@cacheEnables caching for the query, field or type applied to.
@callInvokes a query or mutation from another query or mutation field.
@constAllows embedding of a constant response within the schema.
@graphQLResolves a field or node by a GraphQL API.
@grpcResolves a field or node by a gRPC API.
@httpResolves a field or node by a REST API.
@linkImports external resources such as config files, certs, protobufs, etc in the schema.
@modifyEnables changes to attributes of fields or nodes in the schema.
@omitExcludes fields or nodes from the generated schema, making them inaccessible through the GraphQL API.
@serverProvides server configurations for behavior tuning and tailcall optimization in specific use-cases.
@telemetryIntegrates with open-telemetry to provide observability of the running tailcall service.
@upstreamControls aspects of the upstream server connection, including timeouts and keep-alive settings.
diff --git a/docs/operators/link/index.html b/docs/operators/link/index.html index 5926ce51ef..ca43193d1e 100644 --- a/docs/operators/link/index.html +++ b/docs/operators/link/index.html @@ -16,14 +16,14 @@ - - + +

@link

The @link operator is used for bringing external resources into your GraphQL schema. It makes it easier to include configurations, .proto files for gRPC services, and other files into your schema. With this operator, external resources are either merged with or used effectively in the importing configuration.

+ Star

@link

The @link operator is used for bringing external resources into your GraphQL schema. It makes it easier to include configurations, .proto files for gRPC services, and other files into your schema. With this operator, external resources are either merged with or used effectively in the importing configuration.

How it Works​

The @link directive requires specifying a source src, the resource's type type, and an optional identifier id.