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
- func FilePath(names []string) string
- func Plan(dir string, out Output, opts Options) (*Result, []PlannedFile, error)
- func ReadInput(name string, limit int64) ([]byte, error)
- func ReadLimited(r io.Reader, name string, limit int64) ([]byte, error)
- func RegisterFlags(cmd *cobra.Command, o *Options)
- func StubPath(env string, used map[string]bool) string
- func Summarize(w io.Writer, out Output, res *Result)
- func VariableName(name string) string
- type ErrConflicts
- type GeneratedFile
- type Options
- type Output
- type PlannedFile
- type RawFile
- type Result
- type Skipped
- type Warning
Constants ¶
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.
const MaxInput = 64 << 20
MaxInput is the largest file an importer reads: a collection, a spec sidecar or an environment file.
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
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
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 ¶
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 ¶
ReadLimited reads r, named name in errors, refusing more than limit bytes.
func RegisterFlags ¶
RegisterFlags adds the shared import flags to cmd, bound to o.
func StubPath ¶
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 ¶
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 ¶
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 ¶
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.
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
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).
type Warning ¶
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 ¶
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 ¶
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.
Source Files
¶
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. |