Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cmd/restish-docgen/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -721,7 +721,7 @@ func renderMessageSchemaRegion(root string) (string, error) {
}
for _, group := range [][]string{
{"InitMsg", "HTTPRequestMsg", "HTTPResponseMsg", "APISpecMsg", "APISpecResponseMsg", "APIOperation", "APIParam", "ListAPIsMsg", "ListAPIsResponseMsg", "ListProfilesMsg", "ListProfilesResponseMsg", "ConfigReadMsg", "ConfigReadResponseMsg", "PromptMsg", "PromptResponseMsg", "ConfirmMsg", "ConfirmResponseMsg", "ResponseMsg", "DoneMsg", "StdoutDataMsg", "StderrDataMsg", "WarnMsg", "ProgressMsg", "SpinnerMsg", "LogMsg", "StdinDataMsg", "StdinCloseMsg"},
{"FormatterResponse", "FormatterRequest", "LoaderRequest", "LoaderResponse"},
{"FormatterResponse", "FormatterRequest", "FormatterOutput", "LoaderRequest", "LoaderResponse"},
{"HookRequest", "HookRequestHeaderUpdate", "AuthHookInput", "AuthHookOutput", "RequestMiddlewareInput", "RequestMiddlewareOutput", "HookResponse", "ResponseMiddlewareInput", "FollowRequest", "HookResponseUpdate", "ResponseMiddlewareOutput"},
{"TLSSignerInitMsg", "TLSSignerReadyMsg", "TLSSignerSignMsg", "TLSSignerSignedMsg", "TLSSignerShutdownMsg"},
} {
Expand Down
23 changes: 19 additions & 4 deletions docs/design/019-hook-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,8 +194,22 @@ directly define commands.
Formatter plugins declare `formatter_names` in the manifest. Each declared name
becomes available through `-o <name>`.

Formatter hooks are slightly different from the other hook types because stdout
is treated as raw formatted bytes rather than a CBOR reply.
Formatter hooks are slightly different from the other hook types. By default,
stdout is treated as raw formatted bytes rather than a CBOR reply.

A plugin that requires `formatter.host_fallback` uses framed stdout instead.
Restish adds a non-zero `request_id` to each formatter request. The plugin may
write any number of `formatter-output` CBOR messages containing `data`, which
keeps asynchronous output such as animation possible. It must finish each
request with one message containing the matching `request_id` and
`complete: true`.

On a completing message, `fallback: true` asks Restish to render that request's
body with the built-in `auto` formatter. This lets a specialised formatter pass
through unrelated API errors with the normal indentation, highlighting, and
configured theme. Fallback is only valid for a `start` or `item` request that
carries a body. The plugin must finish writing output related to a request
before completing it.

### Formatter Hook Session

Expand All @@ -217,8 +231,9 @@ same formatter handle:
- paginated output by rendering each `item`
- NDJSON/SSE output by rendering each `item`

The plugin writes raw formatted bytes to stdout as values arrive and exits after
the `end` message or EOF on stdin.
Without `formatter.host_fallback`, the plugin writes raw formatted bytes to
stdout as values arrive. With the feature, it writes `formatter-output` messages
instead. In both modes it exits after the `end` message or EOF on stdin.

This model is intentionally narrow:

Expand Down
9 changes: 6 additions & 3 deletions internal/cli/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ import (
"github.com/rest-sh/restish/v2/internal/output"
internalplugin "github.com/rest-sh/restish/v2/internal/plugin"
"github.com/rest-sh/restish/v2/internal/spec"
pluginwire "github.com/rest-sh/restish/v2/plugin"
"github.com/spf13/cobra"
)

Expand Down Expand Up @@ -649,9 +650,11 @@ func (c *CLI) Run(args []string) error {
if pluginDeclaresHook(p.Manifest, "formatter") {
for _, name := range p.Manifest.FormatterNames {
c.formatters[name] = &output.PluginFormatter{
PluginPath: p.Path,
FormatName: name,
Context: ctx,
PluginPath: p.Path,
FormatName: name,
Context: ctx,
Timeout: internalplugin.HookTimeout(p.Manifest, "formatter"),
HostFallback: manifestRequiresFeature(p.Manifest, pluginwire.FeatureFormatterHostFallback),
}
}
}
Expand Down
50 changes: 50 additions & 0 deletions internal/output/extra_formatters_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ var (
fmtPluginBuildOnce sync.Once
fmtPluginBin string
fmtPluginBuildErr error
fallbackPluginOnce sync.Once
fallbackPluginBin string
fallbackPluginErr error
)

func buildFmtPlugin(t *testing.T) string {
Expand Down Expand Up @@ -55,6 +58,28 @@ func buildFmtPlugin(t *testing.T) string {
return fmtPluginBin
}

func buildFallbackPlugin(t *testing.T) string {
t.Helper()
fallbackPluginOnce.Do(func() {
bin := filepath.Join(os.TempDir(), "restish-test-fallback-output-tests")
if runtime.GOOS == "windows" {
bin += ".exe"
}
_, thisFile, _, _ := runtime.Caller(0)
cmd := exec.Command("go", "build", "-o", bin, "./testdata/fallbackfmt")
cmd.Dir = filepath.Dir(thisFile)
if out, err := cmd.CombinedOutput(); err != nil {
fallbackPluginErr = fmt.Errorf("build fallback plugin: %w\n%s", err, out)
return
}
fallbackPluginBin = bin
})
if fallbackPluginErr != nil {
t.Fatal(fallbackPluginErr)
}
return fallbackPluginBin
}

func tableResp() *output.Response {
return &output.Response{
Proto: "HTTP/1.1",
Expand Down Expand Up @@ -390,3 +415,28 @@ func TestPluginFormatterFormatValueRoundTrip(t *testing.T) {
t.Errorf("expected end event in output, got:\n%s", got)
}
}

func TestPluginFormatterHostFallbackRoundTrip(t *testing.T) {
f := &output.PluginFormatter{
PluginPath: buildFallbackPlugin(t),
FormatName: "testfallback",
HostFallback: true,
}

var buf bytes.Buffer
if err := f.FormatValue(&buf, map[string]any{"message": "cannot match command"}, false); err != nil {
t.Fatalf("FormatValue: %v", err)
}
want := "{\n \"message\": \"cannot match command\"\n}\n"
if got := buf.String(); got != want {
t.Fatalf("output = %q, want %q", got, want)
}

buf.Reset()
if err := f.FormatValue(&buf, "plain text", false); err != nil {
t.Fatalf("FormatValue string: %v", err)
}
if got, want := buf.String(), "plain text\n"; got != want {
t.Fatalf("string output = %q, want %q", got, want)
}
}
Loading
Loading