diff --git a/docs/en/getting-started/introduction/_index.md b/docs/en/getting-started/introduction/_index.md index a6b0426fe9e9..fa173708a198 100644 --- a/docs/en/getting-started/introduction/_index.md +++ b/docs/en/getting-started/introduction/_index.md @@ -136,6 +136,15 @@ Toolbox enables dynamic reloading by default. To disable, use the `--disable-reload` flag. {{< /notice >}} +#### Launching Toolbox UI + +To launch Toolbox's interactive UI, use the `--ui` flag. This allows you to test tools and toolsets +with features such as authorized parameters. To learn more, visit [Toolbox UI](../../how-to/use-toolbox-ui/index.md). + +```sh +./toolbox --ui +``` + #### Homebrew Users If you installed Toolbox using Homebrew, the `toolbox` binary is available in your system path. You can start the server with the same command: diff --git a/docs/en/how-to/use-toolbox-ui/edit-headers.gif b/docs/en/how-to/use-toolbox-ui/edit-headers.gif new file mode 100644 index 000000000000..b63860dca005 Binary files /dev/null and b/docs/en/how-to/use-toolbox-ui/edit-headers.gif differ diff --git a/docs/en/how-to/use-toolbox-ui/edit-headers.png b/docs/en/how-to/use-toolbox-ui/edit-headers.png new file mode 100644 index 000000000000..07aebc07d20f Binary files /dev/null and b/docs/en/how-to/use-toolbox-ui/edit-headers.png differ diff --git a/docs/en/how-to/use-toolbox-ui/index.md b/docs/en/how-to/use-toolbox-ui/index.md new file mode 100644 index 000000000000..aa3fd6688af8 --- /dev/null +++ b/docs/en/how-to/use-toolbox-ui/index.md @@ -0,0 +1,106 @@ +--- +title: "Toolbox UI" +type: docs +weight: 1 +description: > + How to effectively use Toolbox UI. +--- + +Toolbox UI is a built-in web interface that allows users to visually inspect and test out configured resources such as tools and toolsets. + +## Launching Toolbox UI + +To launch Toolbox's interactive UI, use the `--ui` flag. + +```sh +./toolbox --ui +``` + +Toolbox UI will be served from the same host and port as the Toolbox Server, with the `/ui` suffix. Once Toolbox +is launched, the following INFO log with Toolbox UI's url will be shown: + +```bash +INFO "Toolbox UI is up and running at: http://localhost:5000/ui" +``` + +## Navigating the Tools Page + +The tools page shows all tools loaded from your configuration file. This corresponds to the default toolset (represented by an empty string). Each tool's name on this page will exactly match its name in the configuration +file. + +To view details for a specific tool, click on the tool name. The main content area will be populated +with the tool name, description, and available parameters. + +![Tools Page](./tools.png) + +### Invoking a Tool + +1. Click on a Tool +2. Enter appropriate parameters in each parameter field +3. Click "Run Tool" +4. Done! Your results will appear in the response field +5. (Optional) Uncheck "Prettify JSON" to format the response as plain text + +![Run Tool Demo GIF](./run-tool.gif) + +### Optional Parameters + +Toolbox allows users to add [optional parameters](../../resources/tools/#basic-parameters) with or without a default value. + +To exclude a parameter, uncheck the box to the right of an associated parameter, and that parameter will not be +included in the request body. If the parameter is not sent, Toolbox will either use it as `nil` value or the `default` value, if configured. If the parameter is required, Toolbox will throw an error. + +When the box is checked, parameter will be sent exactly as entered in the response field (e.g. empty string). + +![Optional Parameter checked example](./optional-param-checked.png) + +![Optional Parameter unchecked example](./optional-param-unchecked.png) + +### Editing Headers + +To edit headers, press the "Edit Headers" button to display the header modal. Within this modal, +users can make direct edits by typing into the header's text area. + +Toolbox UI validates that the headers are in correct JSON format. Other header-related errors (e.g., +incorrect header names or values required by the tool) will be reported in the Response section +after running the tool. + +![Edit Headers](./edit-headers.png) + +#### Google OAuth + +Currently, Toolbox supports Google OAuth 2.0 as an AuthService, which allows tools to utilize +authorized parameters. When a tool uses an authorized parameter, the parameter will be displayed +but not editable, as it will be populated from the authentication token. + +To provide the token, add your Google OAuth ID Token to the request header using the "Edit Headers" +button and modal described above. The key should be the name of your AuthService as defined in +your tool configuration file, suffixed with `_token`. The value should be your ID token as a string. + +1. Select a tool that requires [authenticated parameters]() +2. The auth parameter's text field is greyed out. This is because it cannot be entered manually and will +be parsed from the resolved auth token +3. To update request headers with the token, select "Edit Headers" +4. Checkout the dropdown "How to extract Google OAuth ID Token manually" for guidance on retrieving ID token +5. Paste the request header +6. Click "Save" +7. Click "Run Tool" + +```json +{ + "Content-Type": "application/json", + "my-google-auth_token": "YOUR_ID_TOKEN_HERE" +} +``` + +![Using Authenticated Parameter GIF](./edit-headers.gif) + +## Navigating the Toolsets Page + +Through the toolsets page, users can search for a specific toolset to retrieve tools from. Simply +enter the toolset name in the search bar, and press "Enter" to retrieve the associated tools. + +If the toolset name is not defined within the tools configuration file, an error message will be +displayed. + +![Toolsets Page](./toolsets.png) diff --git a/docs/en/how-to/use-toolbox-ui/optional-param-checked.png b/docs/en/how-to/use-toolbox-ui/optional-param-checked.png new file mode 100644 index 000000000000..54eff95936ab Binary files /dev/null and b/docs/en/how-to/use-toolbox-ui/optional-param-checked.png differ diff --git a/docs/en/how-to/use-toolbox-ui/optional-param-unchecked.png b/docs/en/how-to/use-toolbox-ui/optional-param-unchecked.png new file mode 100644 index 000000000000..3265adc9bb1b Binary files /dev/null and b/docs/en/how-to/use-toolbox-ui/optional-param-unchecked.png differ diff --git a/docs/en/how-to/use-toolbox-ui/run-tool.gif b/docs/en/how-to/use-toolbox-ui/run-tool.gif new file mode 100644 index 000000000000..58fbc933a794 Binary files /dev/null and b/docs/en/how-to/use-toolbox-ui/run-tool.gif differ diff --git a/docs/en/how-to/use-toolbox-ui/tools.png b/docs/en/how-to/use-toolbox-ui/tools.png new file mode 100644 index 000000000000..3d2934d9f462 Binary files /dev/null and b/docs/en/how-to/use-toolbox-ui/tools.png differ diff --git a/docs/en/how-to/use-toolbox-ui/toolsets.png b/docs/en/how-to/use-toolbox-ui/toolsets.png new file mode 100644 index 000000000000..9eb7a60c4c5b Binary files /dev/null and b/docs/en/how-to/use-toolbox-ui/toolsets.png differ diff --git a/go.mod b/go.mod index 8b39b413e795..f13e5a2807cf 100644 --- a/go.mod +++ b/go.mod @@ -50,6 +50,7 @@ require ( ) require ( + github.com/andybalholm/cascadia v1.3.3 // indirect github.com/duckdb/duckdb-go-bindings v0.1.17 // indirect github.com/duckdb/duckdb-go-bindings/darwin-amd64 v0.1.12 // indirect github.com/duckdb/duckdb-go-bindings/darwin-arm64 v0.1.12 // indirect diff --git a/go.sum b/go.sum index 8f07591523d9..d32068a2fbe7 100644 --- a/go.sum +++ b/go.sum @@ -676,6 +676,8 @@ github.com/ajstarks/svgo v0.0.0-20211024235047-1546f124cd8b/go.mod h1:1KcenG0jGW github.com/andybalholm/brotli v1.0.4/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig= github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ= github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY= +github.com/andybalholm/cascadia v1.3.3 h1:AG2YHrzJIm4BZ19iwJ/DAua6Btl3IwJX+VI4kktS1LM= +github.com/andybalholm/cascadia v1.3.3/go.mod h1:xNd9bqTn98Ln4DwST8/nG+H0yuB8Hmgu1YHNnWw0GeA= github.com/antihax/optional v1.0.0/go.mod h1:uupD/76wgC+ih3iEmQUL+0Ugr19nfwCT1kdvxnR2qWY= github.com/apache/arrow-go/v18 v18.4.0 h1:/RvkGqH517iY8bZKc4FD5/kkdwXJGjxf28JIXbJ/oB0= github.com/apache/arrow-go/v18 v18.4.0/go.mod h1:Aawvwhj8x2jURIzD9Moy72cF0FyJXOpkYpdmGRHcw14= @@ -1231,6 +1233,10 @@ golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPh golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4= golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc= golang.org/x/crypto v0.0.0-20211108221036-ceb1ce70b4fa/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc= +golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliYc= +golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU= +golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8= +golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk= golang.org/x/crypto v0.40.0 h1:r4x+VvoG5Fm+eJcxMaY8CQM7Lb0l1lsmjGBQ6s8BfKM= golang.org/x/crypto v0.40.0/go.mod h1:Qr1vMER5WyS2dfPHAlsOj01wgLbsyWtFn/aY+5+ZdxY= golang.org/x/exp v0.0.0-20180321215751-8460e604b9de/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA= @@ -1354,6 +1360,11 @@ golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= golang.org/x/net v0.7.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= golang.org/x/net v0.8.0/go.mod h1:QVkue5JL9kW//ek3r6jTKnTFis1tRmNAW2P1shuFdJc= golang.org/x/net v0.9.0/go.mod h1:d48xBJpPfHeWQsugry2m+kC02ZBRGRgulfHnEXEuWns= +golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg= +golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk= +golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44= +golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM= +golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4= golang.org/x/net v0.42.0 h1:jzkYrhi3YQWD6MLBJcsklgQsoAcw89EcZbJw8Z614hs= golang.org/x/net v0.42.0/go.mod h1:FF1RA5d3u7nAYA4z2TkclSCKh68eSXtiFwcWQpPXdt8= golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U= @@ -1403,6 +1414,10 @@ golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJ golang.org/x/sync v0.0.0-20220819030929-7fc1605a5dde/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20220929204114-8fcdb60fdcc0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= +golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y= +golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= +golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= +golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sync v0.16.0 h1:ycBJEhp9p4vXvUZNszeOq0kGTPghopOL8q0fq3vstxw= golang.org/x/sync v0.16.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA= golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= @@ -1485,8 +1500,14 @@ golang.org/x/sys v0.4.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.7.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= +golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= +golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA= golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k= +golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE= golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= golang.org/x/term v0.2.0/go.mod h1:TVmDHMZPmdnySmBfhjOoOdhjzdE1h4u1VwSiw2l1Nuc= @@ -1516,6 +1537,10 @@ golang.org/x/text v0.6.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= golang.org/x/text v0.8.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8= golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8= +golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE= +golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= +golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= +golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ= golang.org/x/text v0.27.0 h1:4fGWRpyh641NLlecmyl4LOe6yDdfaYNrGb2zdfo4JV4= golang.org/x/text v0.27.0/go.mod h1:1D28KMCvyooCX9hBiosv5Tz/+YLxj0j7XhWjpSUF7CU= golang.org/x/time v0.0.0-20181108054448-85acf8d2951c/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ= @@ -1590,6 +1615,8 @@ golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc golang.org/x/tools v0.3.0/go.mod h1:/rWhSS2+zyEVwoJf8YAX6L2f0ntZ7Kn/mGgAWcipA5k= golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU= golang.org/x/tools v0.7.0/go.mod h1:4pg6aUX35JBAogB10C9AtvVL+qowtN4pT3CGSQex14s= +golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58= +golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk= golang.org/x/tools v0.34.0 h1:qIpSLOxeCYGg9TrcJokLBG4KFA6d795g0xkBkiESGlo= golang.org/x/tools v0.34.0/go.mod h1:pAP9OwEaY1CAW3HOmg3hLZC5Z0CCmzjAF2UQMSqNARg= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=