Merge branch 'develop' into docs/add-doc-for-http-post-request-batching

tailcallhq · Dec 10, 2024 · b96f220 · b96f220
2 parents d72cf40 + 38d94c0
commit b96f220
Show file tree

Hide file tree

Showing 16 changed files with 265 additions and 953 deletions.
diff --git a/blog/tailcall-n+1-working-2024-08-04.md b/blog/tailcall-n+1-working-2024-08-04.md
@@ -112,7 +112,7 @@ It's simple, expressive and doesn't expose the guts of how data will be queried,
 
 ## The Algorithm
 
-Tailcall reads your [configuration](/docs/tailcall-graphql-configuration-format-conversion), parses it, and internally stores it in an efficient graph data-structure that resembles a `HashMap`. This allows `O(1)` access to a GraphQL type which represented as a node by its name. Once the graph data-structure is ready we make it go through a series of validators, one of them being the **N+1 tracker**.
+Tailcall reads your configuration, parses it, and internally stores it in an efficient graph data-structure that resembles a `HashMap`. This allows `O(1)` access to a GraphQL type which represented as a node by its name. Once the graph data-structure is ready we make it go through a series of validators, one of them being the **N+1 tracker**.
 
 Now, here's where it gets fascinating. We use a Depth-First Search (DFS) algorithm, starting at the root query and traversing all the connected nodes. Let me walk you through this cool process:
 

diff --git a/docs/apollo-federation-subgraph.md b/docs/apollo-federation-subgraph.md
@@ -19,7 +19,7 @@ Skip this step if you don't have entities for now or want to add them later.
 
 Now you need to add [entity resolvers](https://www.apollographql.com/docs/federation/entities/) to the Tailcall config to make it act as a subgraph.
 
-To do this, you need to define resolver on types by using one of the [directives](./configuration.mdx) that resolve the data. Use [`{{.value}}`](https://tailcall.run/docs/graphql-resolver-context-tailcall/#value) to access the fields that act as a federation `@key` and will be provided by the Federation Router when making the request to this subgraph.
+To do this, you need to define resolver on types by using one of the [directives](./directives.md) that resolve the data. Use [`{{.value}}`](https://tailcall.run/docs/graphql-resolver-context-tailcall/#value) to access the fields that act as a federation `@key` and will be provided by the Federation Router when making the request to this subgraph.
 
 ```graphql
 type Post

diff --git a/docs/cli.md b/docs/cli.md
@@ -53,14 +53,6 @@ The `check` command allows for files. Specify each file path, separated by a spa
 tailcall check --schema ./path/to/file1.graphql ./path/to/file2.graphql
 ```
 
-### --format
-
-This is an optional command which allows changing the format of the input file. It accepts `gql` or `graphql`,`yml` or `yaml`, `json` .
-
-```bash
-tailcall check ./path/to/file1.graphql ./path/to/file2.graphql --format json
-```
-
 ### --verify-ssl
 
 Controls SSL/TLS certificate verification when loading remote configuration files.
@@ -119,13 +111,17 @@ tailcall init <file_path>
 
 This command prompts for file creation and configuration, creating the following files:
 
-|                 File Name | Description                                                                                                                             |
-| ------------------------: | --------------------------------------------------------------------------------------------------------------------------------------- |
-| [.tailcallrc.schema.json] | Provides autocomplete in your editor when the configuration is written in `json` or `yml` format.                                       |
-|          [.graphqlrc.yml] | An IDE configuration that references your GraphQL configuration (if it's in `.graphql` format) and the following `.tailcallrc.graphql`. |
-|     [.tailcallrc.graphql] | Contains Tailcall specific auto-completions for `.graphql` format.                                                                      |
+| File Name | Description |
+| --------: | ----------- |
+
+<!-- TODO: uncomment when the Taillcall configuration will in separate file -->
+<!-- | [.tailcallrc.schema.json] | Provides autocomplete in your editor for the tailcall configuration written in `json` or `yml` format.                                       | -->
+
+| [.graphqlrc.yml] | An IDE configuration that references your GraphQL schema and the following `.tailcallrc.graphql`. |
+| [.tailcallrc.graphql] | Contains Tailcall specific auto-completions for `.graphql` format. |
+
+<!-- [.tailcallrc.schema.json]: https://github.com/tailcallhq/tailcall/blob/main/generated/.tailcallrc.schema.json -->
 
-[.tailcallrc.schema.json]: https://github.com/tailcallhq/tailcall/blob/main/generated/.tailcallrc.schema.json
 [.graphqlrc.yml]: https://the-guild.dev/graphql/config/docs
 [.tailcallrc.graphql]: https://github.com/tailcallhq/tailcall/blob/main/generated/.tailcallrc.graphql
 
@@ -181,13 +177,13 @@ To generate a Tailcall GraphQL configuration, provide a configuration file to th
     },
     {
       "proto": {
-        "src": "./news.proto"
+        "src": "./news.proto",
+        "url": "http://127.0.0.1:8080/rpc"
       }
     }
   ],
   "output": {
-    "path": "./output.graphql",
-    "format": "graphQL"
+    "path": "./output.graphql"
   },
   "schema": {
     "query": "Query",
@@ -232,9 +228,9 @@ inputs:
       fieldName: "createPost"
   - proto:
       src: "./news.proto"
+      url: "http://127.0.0.1:8080/rpc"
 output:
   path: "./output.graphql"
-  format: "graphQL"
 schema:
   query: "Query"
   mutation: "Mutation"
@@ -374,36 +370,37 @@ The `inputs` section specifies the sources from which the GraphQL configuration
     }
     ```
 
-4.  **Proto:** For protobuf files, specify the path to the proto file (`src`).
-
-    <Tabs>
-      <TabItem value="json" label="JSON">
-      ```json
-      {
-        "proto": {
-          "src": "./path/to/file.proto"
-        }
-      }
-      ```
-      </TabItem>
-      <TabItem value="yml" label="YML">
-      ```yml
-      - proto:
-          src: "./news.proto"
-      ```
-      </TabItem>
-    </Tabs>
+4.  **Proto:**
+
+    - Specify the **path to the proto file** (`src`) to help Tailcall create a schema and understand the gRPC methods to call when a field is queried.
+    - Specify the **gRPC URL** (`url`) where the gRPC service is hosted.
+    - Include a **boolean parameter** `connectRPC` (optional). If set to `true`, the proto file will be used to generate the schema, but the communication between Tailcall and the upstream will happen using the [Connect-RPC protocol](https://connectrpc.com/docs/protocol/).
+
+        <Tabs>
+          <TabItem value="json" label="JSON">
+          ```json
+          {
+            "proto": {
+              "src": "./path/to/file.proto",
+              "url": "http://127.0.0.1:8080/rpc"
+            }
+          }
+          ```
+          </TabItem>
+          <TabItem value="yml" label="YML">
+          ```yml
+          - proto:
+              src: "./news.proto"
+              url: "http://127.0.0.1:8080/rpc"
+          ```
+          </TabItem>
+        </Tabs>
 
 ### Output
 
-The `output` section specifies the path and format for the generated GraphQL configuration.
+The `output` section specifies the path for the generated GraphQL configuration.
 
 - **path**: The file path where the output will be saved.
-- **format**: The format of the output file. Supported formats are `json`, `yml`, and `graphQL`.
-
-:::tip
-You can also change the format of the configuration later using the [check](#--format) command.
-:::
 
 ### Preset
 
@@ -573,7 +570,7 @@ preset:
    }
    ```
 
-   By leveraging field names to derive type names, the schema becomes more intuitive and aligned with the data it represents, enhancing overall readability and understanding.
+   By leveraging field names to derive type names, the schema becomes more intuitive and aligned with the data it represents, enhancing overall readability and understanding. You can learn more about config autogen [here](./config-generation.md).
 
 ### LLM
 

diff --git a/docs/config-generation.md b/docs/config-generation.md
@@ -134,16 +134,21 @@ Tailcall simplifies GraphQL schema generation from REST APIs, supporting various
     - **format**: Specifies the output format as GraphQL (in above example, it's `graphQL`).
 
 To generate the GraphQL configuration run following command
+
 <Tabs>
-<TabItem value="json" label="JSON Config Format">
-`bash
-    tailcall gen ./config.json
-    `
-</TabItem>
 <TabItem value="yml" label="YML Config Format">
-`bash
-    tailcall gen ./config.yml
-    `
+
+```bash
+tailcall gen ./config.yml
+```
+
+</TabItem>
+<TabItem value="json" label="JSON Config Format">
+
+```bash
+tailcall gen ./config.json
+```
+
 </TabItem>
 </Tabs>
 **Schema**: Specifies the name of the Query operation type, which is `Query` in this example.
@@ -288,7 +293,7 @@ tailcall gen ./config.json
   </TabItem>
   </Tabs>
 
-**Schema**: Specifies the operation type. In this example, it's a `Mutation` operation with the name `Mutation`.
+Generated Configuration looks like following.
 
 ```graphql showLineNumbers title="Generated GraphQL Configuration"
 schema @server @upstream {
@@ -342,6 +347,13 @@ Tailcall simplifies the process of generating GraphQL schemas from gRPC. By spec
                   "src": "./news.proto",
                   "url": "http://localhost:50051"
                 }
+              },
+              {
+                "proto": {
+                  "src": "./news.proto",
+                  "url": "http://localhost:8080/news.NewsService/",
+                  "connectRPC": true
+                }
               }
             ],
             "preset": {
@@ -365,6 +377,10 @@ Tailcall simplifies the process of generating GraphQL schemas from gRPC. By spec
           - proto:
             src: "./news.proto"
             url: "http://localhost:50051"
+          - proto:
+            src: "./news.proto"
+            url: "http://localhost:8080/news.NewsService/"
+            connectRPC: true
         preset:
           mergeType: 1.0
         output:
@@ -382,6 +398,8 @@ Let's understand the above configuration file.
 **Proto**: Defines the path to the proto file that the configuration interacts with.
 
 - **src**: Specifies the path to the proto file (`./news.proto` in this example).
+- **url**: Specifies the url on which gRPC service is hosted. (`http://localhost:50051` in this example).
+- **connectRPC**: An optional flag indicating whether Tailcall should generate [`Connect-RPC`](https://connectrpc.com/docs/protocol/) compatible configuration.
 
 **Preset**: We've applied only one tuning parameter for the configuration. let's understand it in short.
 
@@ -436,7 +454,8 @@ Here is an example configuration that demonstrates how to set up a hybrid integr
     },
     {
       "proto": {
-        "src": "./news.proto"
+        "src": "./news.proto",
+        "url": "http://localhost:50051"
       }
     }
   ],
@@ -462,6 +481,7 @@ inputs:
       fieldName: "posts"
   - proto:
       src: "./news.proto"
+      url: "http://localhost:50051"
 preset:
   mergeType: 1.0
 output:
@@ -495,20 +515,23 @@ Let's understand the above configuration file.
 - **format**: Specifies the output format as GraphQL (in above example, it's `graphQL`).
 
 To generate the GraphQL configuration run following command
+
 <Tabs>
+<TabItem value="yml" label="YML Config Format">
+
+```bash
+tailcall gen ./config.yml
+```
+
+</TabItem>
 <TabItem value="json" label="JSON Config Format">
 
 ```bash
 tailcall gen ./config.json
 ```
 
-  </TabItem>
-  <TabItem value="yml" label="YML Config Format">
-    ```bash
-    tailcall gen ./config.yml
-    ```
-  </TabItem>
-  </Tabs>
+</TabItem>
+</Tabs>
 **Schema**: Specifies the name of the Query operation type, which is `Query` in this example.
 
 ```graphql showLineNumbers
@@ -974,7 +997,8 @@ curl:
     },
     {
       "proto": {
-        "src": "./news.proto"
+        "src": "./news.proto",
+        "url": "http://localhost:50051"
       }
     }
   ],
@@ -995,6 +1019,7 @@ inputs:
       fieldName: "posts"
   - proto:
       src: "./news.proto"
+      url: "http://localhost:50051"
 schema:
   query: "Query"
 ```