convert

package
v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 5, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package convert is the shared writer importers (curl, Postman, OpenCollection, .http, OpenAPI) use to turn generated request files into files on disk: path sanitizing, collision handling, a sandboxed atomic write and a sonde.yaml skeleton that is never overwritten.

Index

Constants

View Source
const (
	// WarnUnsupportedAuth: an auth scheme with no Sonde equivalent.
	WarnUnsupportedAuth = "unsupported-auth"
	// WarnUnsupportedBody: a body left out or reduced.
	WarnUnsupportedBody = "unsupported-body"
	// WarnUnsupportedOption: an option or flag with no Sonde equivalent.
	WarnUnsupportedOption = "unsupported-option"
	// WarnScript: a script kept as a comment, never run.
	WarnScript = "script"
	// WarnDynamicVariable: a dynamic variable with no Sonde function.
	WarnDynamicVariable = "dynamic-variable"
	// WarnSecret: a secret value left out of the output.
	WarnSecret = "secret"
	// WarnUnsupported: any other item that could not be converted
	// faithfully.
	WarnUnsupported = "unsupported"
)

Warning kinds shared by the importers.

View Source
const MaxInput = 64 << 20

MaxInput is the largest file an importer reads: a collection, a spec sidecar or an environment file.

View Source
const ProjectFileName = "sonde.yaml"

ProjectFileName is the sonde.yaml skeleton's file name inside DIR.

Variables

This section is empty.

Functions

func FilePath added in v1.4.0

func FilePath(names []string) string

FilePath joins the names of the folders and the request to a GeneratedFile Path: a slash in a name is part of the name ("Enable / disable"), never a folder of its own.

func Plan added in v1.4.0

func Plan(dir string, out Output, opts Options) (*Result, []PlannedFile, error)

Plan computes what Write does with out in dir under opts, without writing anything: the Result, and the files to write in order. A missing dir has no files yet. Without opts.Force, planned files that already exist are an *ErrConflicts.

func ReadInput

func ReadInput(name string, limit int64) ([]byte, error)

ReadInput reads the file an importer is given, at most limit bytes. It refuses anything but a regular file, before opening it, so a named pipe can't block the import.

func ReadLimited

func ReadLimited(r io.Reader, name string, limit int64) ([]byte, error)

ReadLimited reads r, named name in errors, refusing more than limit bytes.

func RegisterFlags

func RegisterFlags(cmd *cobra.Command, o *Options)

RegisterFlags adds the shared import flags to cmd, bound to o.

func StubPath

func StubPath(env string, used map[string]bool) string

StubPath returns the path of the secrets stub of environment env, "secrets/<env>.secrets" with env sanitized like a path segment, distinct from every path already in used, which it records.

func Summarize

func Summarize(w io.Writer, out Output, res *Result)

Summarize writes a deterministic, human-readable summary of a Write to w: files written (or planned, for a dry run), the number of requests, skipped items with their reasons, and warnings grouped by kind. Callers typically pass cmd.ErrOrStderr().

func VariableName

func VariableName(name string) string

VariableName returns name as a valid Sonde variable name: every character other than a letter, a digit, '_' or '-' becomes '_', and a name clashing with a Sonde function gets a "var_" prefix. Importers use it for both the placeholders and the variable definitions, so the two always match.

Types

type ErrConflicts

type ErrConflicts struct{ Files []string }

ErrConflicts is returned by Write when Options.Force is false and one or more planned files already exist in DIR: nothing was written.

func (*ErrConflicts) Error

func (e *ErrConflicts) Error() string

type GeneratedFile

type GeneratedFile struct {
	Path string
	File *syntax.File
}

GeneratedFile is one request file an importer produced. Path is a relative, slash-separated path without extension (e.g. "pets/list-pets"); Write appends ".hurl" or ".sonde", sanitizes every segment and resolves collisions among the files of one Output.

type Options

type Options struct {
	// Output is the target directory (-o/--output); required.
	Output string
	// Ext is the extension generated files get, without the dot: "hurl"
	// (default) or "sonde".
	Ext string
	// Force allows overwriting files that already exist in Output. It
	// never applies to an existing sonde.yaml, which Write always leaves
	// untouched.
	Force bool
	// DryRun prints the plan and writes nothing.
	DryRun bool
}

Options are the flags every importer command shares.

func (Options) Dialect

func (o Options) Dialect() syntax.Dialect

Dialect is the dialect of the generated files, the one syntax.DialectFor picks for their extension.

type Output

type Output struct {
	// Files are the generated request files.
	Files []GeneratedFile
	// Extra are the other files, written next to the request files.
	Extra []RawFile
	// ProjectYAML is an optional sonde.yaml skeleton (config.EmitProject's
	// output); nil means the importer has nothing to add to a project file.
	ProjectYAML []byte
	// Warnings are non-fatal notes about the conversion.
	Warnings []Warning
	// Skipped are input items the importer chose not to convert.
	Skipped []Skipped
}

Output is everything one importer run produces.

type PlannedFile added in v1.4.0

type PlannedFile struct {
	Path string
	Data []byte
	Perm fs.FileMode
}

PlannedFile is a file Write writes: its path relative to DIR (slash-separated), its content and its permission.

type RawFile

type RawFile struct {
	Path string
	Data []byte
	// Keep marks a file a user goes on to fill in, such as a secrets stub:
	// it is written 0o600 and, like sonde.yaml, never overwritten, even
	// with --force.
	Keep bool
}

RawFile is a file other than a request file an importer produced, such as a variables file or a secrets stub. Path is relative and slash-separated, with its extension; Write sanitizes it like a request file's path and keeps it distinct from every other planned file.

type Result

type Result struct {
	// DryRun is Options.DryRun: Files and Project below were computed but
	// nothing was written.
	DryRun bool
	// Files are the relative paths written (or planned), sorted.
	Files []string
	// RequestCount is the number of entries across every written file.
	RequestCount int
	// Project is the sonde.yaml path written (or planned), "" if Output had
	// no ProjectYAML or DIR/sonde.yaml already existed.
	Project string
	// ProjectSkipped is true when Output.ProjectYAML was set but
	// DIR/sonde.yaml already existed, so it was left untouched.
	ProjectSkipped bool
	// Extra are the relative paths of Output.Extra written (or planned),
	// sorted.
	Extra []string
	// ExtraKept are the Output.Extra files marked Keep that already
	// existed and were left untouched, sorted.
	ExtraKept []string
}

Result summarizes a Write (or, with Options.DryRun, the plan Write would have carried out).

func Write

func Write(dir string, out Output, opts Options) (*Result, error)

Write formats and writes out into dir under opts. With opts.DryRun set, it computes the same plan and returns it without touching the filesystem. dir is created if missing; every other write is confined inside it (including through a symbolic link) using os.Root.

type Skipped

type Skipped struct {
	Name   string
	Reason string
}

Skipped is an input item an importer chose not to convert, and why.

type Warning

type Warning struct {
	Kind    string
	Message string
}

Warning is a non-fatal note about the conversion, grouped by Kind in the summary. Importers use the Warn* kinds below where one fits, so users can grep the same kind across formats.

func JSONBody

func JSONBody(text string) (body *syntax.BodySpec, warns []Warning, ok bool)

JSONBody rebuilds text, one JSON value whose strings may hold {{name}} placeholders, as a syntax JSON body: members keep their order (and duplicates), numbers their spelling, and strings go through ParseText. ok is false when text is not exactly one JSON value, nests deeper than 512 levels, or has a placeholder in an object key; callers then keep the text as is with syntax.TextBody(ParseText(text), "json").

func ParseText

func ParseText(s string) (syntax.Text, []Warning)

ParseText converts a string holding {{name}} placeholders, as Postman, Bruno and .http files write them, to a syntax.Text. Spaces inside the braces are ignored; a name is made valid with VariableName; a dynamic variable ({{$uuid}}) becomes the matching Sonde function, or, without one, a variable of the same name and a WarnDynamicVariable warning. An unclosed "{{" is literal text.

Directories

Path Synopsis
Package curl imports curl command lines into Sonde request files, and (see engine/curl_export.go, internal/cli/export.go) supports exporting entries back to curl.
Package curl imports curl command lines into Sonde request files, and (see engine/curl_export.go, internal/cli/export.go) supports exporting entries back to curl.
Package httpfile imports ".http" files, the plain-text request format shared (with minor dialect differences) by the JetBrains HTTP Client and the VS Code REST Client extension, into Sonde request files.
Package httpfile imports ".http" files, the plain-text request format shared (with minor dialect differences) by the JetBrains HTTP Client and the VS Code REST Client extension, into Sonde request files.
Package opencollection imports a Bruno OpenCollection YAML collection — a single file or a directory — into Sonde request files, through the shared internal/convert writer.
Package opencollection imports a Bruno OpenCollection YAML collection — a single file or a directory — into Sonde request files, through the shared internal/convert writer.
Package postman imports a Postman Collection v2.1 (or v2.0, which the same schema also parses) into Sonde request files: folders become directories, collection and environment variables become a sonde.yaml skeleton, and pre-request/test scripts are kept as comments, never executed.
Package postman imports a Postman Collection v2.1 (or v2.0, which the same schema also parses) into Sonde request files: folders become directories, collection and environment variables become a sonde.yaml skeleton, and pre-request/test scripts are kept as comments, never executed.
Package suggest reads the test scripts of an imported collection (never executed) as edits to its files, for a user to accept one by one: asserts and captures.
Package suggest reads the test scripts of an imported collection (never executed) as edits to its files, for a user to accept one by one: asserts and captures.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL