svchost

Documentation

Overview

Package svchost deals with the representations of the so-called "friendly hostnames" that we use to represent systems that provide Terraform-native remote services, such as module registry, remote operations, etc.

Friendly hostnames are specified such that, as much as possible, they are consistent with how web browsers think of hostnames, so that users can bring their intuitions about how hostnames behave when they access a Terraform Enterprise instance's web UI (or indeed any other website) and have this behave in a similar way.

Index

• func ForDisplay(given string) string
• func IsValid(given string) bool
• type Hostname
  • func ForComparison(given string) (Hostname, error)
  • func (h Hostname) ForDisplay() string
  • func (h Hostname) GoString() string
  • func (h Hostname) String() string

Functions

func ForDisplay

func ForDisplay(given string) string

ForDisplay takes a user-specified hostname and returns a normalized form of it suitable for display in the UI.

If the input is so invalid that no normalization can be performed then this will return the input, assuming that the caller still wants to display _something_. This function is, however, more tolerant than the other functions in this package and will make a best effort to prepare _any_ given hostname for display.

For validation, use either IsValid (for explicit validation) or ForComparison (which implicitly validates, returning an error if invalid).

func IsValid

func IsValid(given string) bool

IsValid returns true if the given user-specified hostname is a valid service hostname.

Validity is determined by complying with the RFC 5891 requirements for names that are valid for domain lookup (section 5), with the additional requirement that user-supplied forms must not _already_ contain Punycode segments.

Types

type Hostname

type Hostname string

Hostname is specialized name for string that indicates that the string has been converted to (or was already in) the storage and comparison form.

Hostname values are not suitable for display in the user-interface. Use the ForDisplay method to obtain a form suitable for display in the UI.

Unlike user-supplied hostnames, strings of type Hostname (assuming they were constructed by a function within this package) can be compared for equality using the standard Go == operator.

func ForComparison

func ForComparison(given string) (Hostname, error)

ForComparison takes a user-specified hostname and returns a normalized form of it suitable for storage and comparison. The result is not suitable for display to end-users because it uses Punycode to represent non-ASCII characters, and this form is unreadable for non-ASCII-speaking humans.

The result is typed as Hostname -- a specialized name for string -- so that other APIs can make it clear within the type system whether they expect a user-specified or display-form hostname or a value already normalized for comparison.

The returned Hostname is not valid if the returned error is non-nil.

func (Hostname) ForDisplay

func (h Hostname) ForDisplay() string

ForDisplay returns a version of the receiver that is appropriate for display in the UI. This includes converting any punycode labels to their corresponding Unicode characters.

A round-trip through ForComparison and this ForDisplay method does not guarantee the same result as calling this package's top-level ForDisplay function, since a round-trip through the Hostname type implies stricter handling than we do when doing basic display-only processing.

func (Hostname) GoString

func (h Hostname) GoString() string

func (Hostname) String

func (h Hostname) String() string