first stab at v2 layout

Signed-off-by: Frédéric BIDON <[email protected]>

Author: fredbi

docs/V2.md

@@ -4,19 +4,24 @@
 
   * [x] Make `uri.URI` a concrete type
   * In theory, this is a breaking change, but has most likely little impact on actual usage
+    * [x] Checked that this wouldn't break fyne-io/fyne
 
   * [x] The interface abstraction comes at a (small) performance cost, and there is no palatable benefit from it
-  * More methods from `URL` should be supported by `URI`, e.g. `UnmarshalText()`, `MarshalBinary()`, `Redacted()`, `IsAbs()`...
+  * More methods from `URL` should be supported by `URI`, e.g. :
+    * [x] `UnmarshalText()`,
+    * [x] `MarshalBinary()`,
+    * `Redacted()`, `IsAbs()`...
   * Similarly, support more methods from `net/url.UserInfo` in the `Authority` type.
   * However:
-    * Let's keep the `Authority` part, as it better sticks to how the object is structured according to the RFC.
-    * Let's keep the fluent `Builder` component. I don't think that exposing fields like in `URL` is a good choice.
+    * [x] Let's keep the `Authority` part, as it better sticks to how the object is structured according to the RFC.
+    * [x] Let's keep the fluent `Builder` component. I don't think that exposing fields like in `URL` is a good choice.
+    * [x] Remove `Authority` and `Builder` interfaces.
 
 ## Canonicalization 
-  * Extra feature: no breaking change
+  * Extra features only: no breaking change
 
-  * `URI.String()` currently just prints out the URL. We may leave it like this.
-  * A `Normalize()` method should canonicalize the URI (case, simplified path, etc), like the `purell` package does.
+  * [x] `URI.String()` currently just prints out the URL. We may leave it like this.
+  * `Normalize()` and `Normaized()` methods should canonicalize the URI (case, simplified path, etc), like the `purell` package does.
     Notice that `purell` seems to be no longer maintained: pulling a dependency is probably not appropriate.  
 
 ## Strictness/compliance options
@@ -29,11 +34,15 @@
     * callers should be able to opt in for IRI vs strict (historical) URI - e.g. only ASCII - rather than the current mixed 
     implementation (yet again, that was a pragmatic... still pondering if putting more nitpicking is appropriate).
     * [x] callers should be able to configure DNS schemes from options rather than overriding a package-level variable
-    * default options could be set at the package level to save on systematic option resolution at parsing time
+    * [x] default options could be set at the package level to save on systematic option resolution at parsing time
     (alternatively, expose a `Parser` type to wrap options once for a series of subsequent calls to `Parse()`/`Validate()`)
     * support canonicalization options with flags such as those defined in `https://pkg.go.dev/golang.org/x/net/idna`
+    * add windows-friendly tolerance option for windows file paths (`Normalize()` would produce a RFC-compliant form)
 
   * Standard compliance improvements
     * Improve IRI support: current support for IRI is at best loose, albeit pragmatic
       (currently, a valid ALPHA token is a unicode letter codepoint, only ASCII digits are supported)
 
+## Performance 
+  * Introduce `Make` methods to return a struct rather than a pointer: this saves an allocation
+    for most use cases in which it is not necessary to get a pointer receiver.

go.mod

@@ -5,12 +5,14 @@ go 1.20
 require (
 	github.com/pkg/profile v1.7.0
 	github.com/stretchr/testify v1.8.4
+	golang.org/x/net v0.15.0
 )
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/felixge/fgprof v0.9.3 // indirect
 	github.com/google/pprof v0.0.0-20211214055906-6f57359322fd // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	golang.org/x/text v0.13.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -19,7 +19,11 @@ github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+golang.org/x/net v0.15.0 h1:ugBLEUaxABaB5AJqW9enI0ACdci2RUd4eP51NTBvuJ8=
+golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
 golang.org/x/sys v0.0.0-20211007075335-d3039528d8ac/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/text v0.13.0 h1:ablQoSUd0tRdKxZewP80B+BaqeKJuVhuRxj/dkrun3k=
+golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

normalize.go

@@ -1,5 +1,25 @@
 package uri
 
-func (u *URI) Normalize() string {
+import "strings"
+
+// Normalize yields a canonicalized representation of the URI.
+func (u URI) Normalize() string {
+	return u.Normalized().String()
+}
+
+// Normalized yields a new URI with normalized content.
+//
+// Calling String() on that one would produce the same string as calling
+// Normalize() on the original URI.
+func (u URI) Normalized() URI {
+	return URI{
+		scheme: strings.ToLower(u.scheme),
+		authority: Authority{
+			path: normalizedPath(u.authority.path),
+		},
+	} // TODO
+}
+
+func normalizedPath(path string) string {
 	return "" // TODO
 }

options.go

@@ -1,37 +1,108 @@
+// nolint
 package uri
 
+import (
+	"sync"
+
+	"golang.org/x/net/idna"
+)
+
 type (
+	// Option allows for fine-grained tuning of tolerances to standards
+	// when validating an URI
 	Option func(*options)
 
 	options struct {
-		schemeIsDNSFunc func(string) bool
-		withStrictASCII bool
-		withStrictIPv6  bool
+		schemeIsDNSFunc       func(string) bool
+		withDNSHostValidation bool
+		withStrictASCII       bool
+		withStrictIPv6        bool
+		withURIReference      bool
+		withStrictIRI         bool
+		withWindowsFriendly   bool
+		withRedactedPassword  bool
+		iDNAFlags             []idna.Option
 	}
 )
 
-var packageLevelDefaults = options{
-	schemeIsDNSFunc: UsesDNSHostValidation,
-}
+var (
+	packageLevelDefaults = options{
+		schemeIsDNSFunc: UsesDNSHostValidation,
+	}
+
+	muxDefaults sync.Mutex
+)
 
 func defaultOptions() *options {
-	o := packageLevelDefaults
+	o := packageLevelDefaults // shallow-clone defaults
 
 	return &o
 }
 
+func applyOptions(opts []Option) *options {
+	if len(opts) == 0 {
+		// no overrides, no need to allocate a copy of the options
+		return &packageLevelDefaults
+	}
+
+	o := defaultOptions()
+
+	for _, apply := range opts {
+		apply(o)
+	}
+
+	return o
+}
+
+// SetDefaultOptions allows to tweak package level defaults.
+//
+// You should only use this in initialization steps, as this manipulates
+// a package global variable.
 func SetDefaultOptions(opts ...Option) {
+	muxDefaults.Lock()
+	defer muxDefaults.Unlock()
 
+	o := &packageLevelDefaults
+	for _, apply := range opts {
+		apply(o)
+	}
 }
 
+// WithSchemeIsDNSFunc overrides the default DNS scheme identification function.
+//
+// The passed function is assumed to return true whenever a (lower cased) scheme
+// should be considered to use DNS-compliant host names.
 func WithSchemeIsDNSFunc(fn func(string) bool) Option {
 	return func(o *options) {
 		o.schemeIsDNSFunc = fn
 	}
 }
 
+// WithDNSSchemes adds extra schemes to the DNS host name validation.
 func WithDNSSchemes(schemes ...string) Option {
 	return func(o *options) {
 		// TODO
 	}
 }
+
+// WithReference tells the validator whether to accept URI references.
+func WithReference(enabled bool) Option {
+	return func(o *options) {
+		o.withURIReference = enabled
+	}
+}
+
+// WithStrictIRI tells the validator to be strict regarding RFCxyz for IRIs
+func WithStrictIRI(enabled bool) Option {
+	return func(o *options) {
+		o.withStrictIRI = enabled
+	}
+}
+
+// WithWindowsFriendly tells the validator to accept Windows file paths that
+// are common, but formally invalid URI path (e.g. 'C:\folder\File.txt').
+func WithWindowsFriendly(enabled bool) Option {
+	return func(o *options) {
+		o.withWindowsFriendly = enabled
+	}
+}

todo.go

@@ -0,0 +1,43 @@
+package uri
+
+func (u *URI) JoinPath(elem ...string) *URI {
+	// TODO: builder method
+	return nil
+}
+
+func (u URI) RequestURI() string {
+	return "" // TODO
+}
+
+func (u *URI) ResolveReference(ref URI) *URI {
+	return nil // TODO
+}
+
+func (u URI) EscapedFragment() string {
+	// TODO
+	return u.fragment
+}
+
+func (u URI) IsReference() bool {
+	return false // TODO
+}
+
+func (a Authority) Redacted() string { // NOTE: net/url.URL mutates
+	return "" // TODO
+}
+
+func (a Authority) Username() string {
+	return ""
+}
+
+func (a Authority) User() string {
+	return ""
+}
+
+func (a Authority) Password() (string, bool) {
+	return "", false
+}
+
+func (a Authority) SetUserPassword(username, password string) *URI {
+	return nil
+}