V2 with options

Signed-off-by: Frederic BIDON <[email protected]>

Author: fredbi

README.md

@@ -21,8 +21,31 @@ which provides a workable but loose implementation of the RFC for URLs.
 
 ## What's new?
 
-### V1.2 announcement
+### v2.0.0
+
+**Breaking changes**
+
+Most users should not be affected by these breaking changes.
+
+* `URI` and `Authority` become concrete types. Interfaces are discarded.
+* `Parse()` and `ParseReference()` now return a `URI` value, no longer a pointer.
+* The `Validate() error` methods have been removed: validation is carried out when parsing only.
+* The `Builder` interface and `URI.Builder()` function have been removed.
+  `URI` exposes fluent builder methods instead.
+* `UsesDNSHostValidation()` has been removed and replaced by a private default function.
+  Override is possible via `Option`. Similar custom behavior may be achieved for `DefaultPort()`.
+
+**Features**
 
+* `Parse(string, ...Option)` and `ParseReference(string, ...Option)` now support options to tune the
+  `URI` validation.
+
+**Performances**
+
+* perf: massive improvement due to giving up pointers (parsing now is a zero-allocation operation).
+  This boosts `Parse()` to be even faster than the standard library `net/url.Parse()`.
+
+### V1.2 announcement
 To do before I cut a v1.2.0:
 * [] handle empty fragment, empty query.
   Ex: `https://host?` is not equivalent to `http://host`.

benchmark_test.go

@@ -90,29 +90,29 @@ func Benchmark_String(b *testing.B) {
 	var ip ipType
 	tests := []URI{
 		{
-			"foo", "//example.com:8042/over/there", "name=ferret", "nose",
-			Authority{"//", "", "example.com", "8042", "/over/there", ip, nil},
 			nil,
+			"foo", "//example.com:8042/over/there", "name=ferret", "nose",
+			Authority{nil, "//", "", "example.com", "8042", "/over/there", ip},
 		},
 		{
-			"http", "//httpbin.org/get", "utf8=\xe2\x98\x83", "",
-			Authority{"//", "", "httpbin.org", "", "/get", ip, nil},
 			nil,
+			"http", "//httpbin.org/get", "utf8=\xe2\x98\x83", "",
+			Authority{nil, "//", "", "httpbin.org", "", "/get", ip},
 		},
 		{
-			"mailto", "[email protected]", "", "",
-			Authority{"//", "user", "domain.com", "", "", ip, nil},
 			nil,
+			"mailto", "[email protected]", "", "",
+			Authority{nil, "//", "user", "domain.com", "", "", ip},
 		},
 		{
-			"ssh", "//[email protected]:29418/openstack/keystone.git", "", "",
-			Authority{"//", "user", "git.openstack.org", "29418", "/openstack/keystone.git", ip, nil},
 			nil,
+			"ssh", "//[email protected]:29418/openstack/keystone.git", "", "",
+			Authority{nil, "//", "user", "git.openstack.org", "29418", "/openstack/keystone.git", ip},
 		},
 		{
-			"https", "//willo.io/", "", "yolo",
-			Authority{"//", "", "willo.io", "", "/", ip, nil},
 			nil,
+			"https", "//willo.io/", "", "yolo",
+			Authority{nil, "//", "", "willo.io", "", "/", ip},
 		},
 	}
 

builder.go

@@ -2,99 +2,131 @@ package uri
 
 // Builder methods
 
-func (u URI) WithScheme(scheme string) URI {
+func (u URI) WithScheme(scheme string, opts ...Option) URI {
 	if u.Err() != nil {
 		return u
 	}
 
+	opts = append(opts, withValidationFlags(flagValidateScheme|flagValidateHost))
+	o, redeem := applyURIOptions(opts)
+	defer func() { redeem(o) }()
+
 	u.scheme = scheme
-	u.authority.ipType, u.err = u.validate()
+	u.authority.ipType, u.err = u.validate(o)
 
 	return u
 }
 
-func (u URI) WithAuthority(authority Authority) URI {
+func (u URI) WithAuthority(authority Authority, opts ...Option) URI {
 	if u.Err() != nil {
 		return u
 	}
 
+	opts = append(opts, withValidationFlags(flagValidateHost|flagValidatePort|flagValidateUserInfo|flagValidatePath))
+	o, redeem := applyURIOptions(opts)
+	defer func() { redeem(o) }()
+
 	u.authority = authority
-	u.authority.ipType, u.err = u.validate()
+	u.authority.ipType, u.err = u.validate(o)
 	u.authority.err = u.err
 
 	return u
 }
 
-func (u URI) WithUserInfo(userinfo string) URI {
+func (u URI) WithUserInfo(userinfo string, opts ...Option) URI {
 	if u.Err() != nil {
 		return u
 	}
 
+	opts = append(opts, withValidationFlags(flagValidateUserInfo))
+	o, redeem := applyURIOptions(opts)
+	defer func() { redeem(o) }()
+
 	u.authority = u.authority.withEnsuredAuthority()
 	u.authority.userinfo = userinfo
-	u.authority.ipType, u.err = u.validate()
+	u.authority.ipType, u.err = u.validate(o)
 	u.authority.err = u.err
 
 	return u
 }
 
-func (u URI) WithHost(host string) URI {
+func (u URI) WithHost(host string, opts ...Option) URI {
 	if u.Err() != nil {
 		return u
 	}
 
+	opts = append(opts, withValidationFlags(flagValidateHost|flagValidatePort))
+	o, redeem := applyURIOptions(opts)
+	defer func() { redeem(o) }()
+
 	u.authority = u.authority.withEnsuredAuthority()
 	u.authority.host = host
-	u.authority.ipType, u.err = u.validate()
+	u.authority.ipType, u.err = u.validate(o)
 	u.authority.err = u.err
 
 	return u
 }
 
-func (u URI) WithPort(port string) URI {
+func (u URI) WithPort(port string, opts ...Option) URI { // TODO: port as int?
 	if u.Err() != nil {
 		return u
 	}
 
+	opts = append(opts, withValidationFlags(flagValidatePort))
+	o, redeem := applyURIOptions(opts)
+	defer func() { redeem(o) }()
+
 	u.authority = u.authority.withEnsuredAuthority()
 	u.authority.port = port
-	u.authority.ipType, u.err = u.validate()
+	u.authority.ipType, u.err = u.validate(o)
 	u.authority.err = u.err
 
 	return u
 }
 
-func (u URI) WithPath(path string) URI {
+func (u URI) WithPath(path string, opts ...Option) URI {
 	if u.Err() != nil {
 		return u
 	}
 
+	opts = append(opts, withValidationFlags(flagValidatePath))
+	o, redeem := applyURIOptions(opts)
+	defer func() { redeem(o) }()
+
 	u.authority = u.authority.withEnsuredAuthority()
 	u.authority.path = path
-	u.authority.ipType, u.err = u.validate()
+	u.authority.ipType, u.err = u.validate(o)
 	u.authority.err = u.err
 
 	return u
 }
 
-func (u URI) WithQuery(query string) URI {
+func (u URI) WithQuery(query string, opts ...Option) URI {
 	if u.Err() != nil {
 		return u
 	}
 
+	opts = append(opts, withValidationFlags(flagValidateQuery))
+	o, redeem := applyURIOptions(opts)
+	defer func() { redeem(o) }()
+
 	u.query = query
-	u.authority.ipType, u.err = u.validate()
+	u.authority.ipType, u.err = u.validate(o)
 
 	return u
 }
 
-func (u URI) WithFragment(fragment string) URI {
+func (u URI) WithFragment(fragment string, opts ...Option) URI {
 	if u.Err() != nil {
 		return u
 	}
 
+	opts = append(opts, withValidationFlags(flagValidateFragment))
+	o, redeem := applyURIOptions(opts)
+	defer func() { redeem(o) }()
+
 	u.fragment = fragment
-	u.authority.ipType, u.err = u.validate()
+	u.authority.ipType, u.err = u.validate(o)
 
 	return u
 }

dns.go

@@ -14,7 +14,7 @@ import (
 // in case you need specific schemes to validate the host as a DNS name.
 //
 // See: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml
-// TODO: now pass it as an option.
+// TODO: now pass it as an option. make private
 var UsesDNSHostValidation = func(scheme string) bool {
 	switch scheme {
 	// prioritize early exit on most commonly used schemes

dns_test.go

@@ -18,6 +18,7 @@ func TestDNSvsHost(t *testing.T) {
 }
 
 func TestValidateHostForScheme(t *testing.T) {
+	o := defaultOptions()
 	for _, host := range []string{
 		"a.b.c",
 		"a",
@@ -32,7 +33,7 @@ func TestValidateHostForScheme(t *testing.T) {
 		"a.b.c.d%30",
 		"a.b.c.%55",
 	} {
-		require.NoErrorf(t, validateHostForScheme(host, "http"),
+		require.NoErrorf(t, validateHostForScheme(host, "http", o),
 			"expected host %q to validate",
 			host,
 		)
@@ -62,7 +63,7 @@ func TestValidateHostForScheme(t *testing.T) {
 		"%",
 		"%X",
 	} {
-		require.Errorf(t, validateHostForScheme(host, "http"),
+		require.Errorf(t, validateHostForScheme(host, "http", o),
 			"expected host %q NOT to validate",
 			host,
 		)

docs/BENCHMARKS.md

@@ -295,3 +295,31 @@ Benchmark_DNSSchemes/with_switch
 Benchmark_DNSSchemes/with_switch-16                	1000000000	         3.044 ns/op	       0 B/op	       0 allocs/op
 PASS
 
+# V2 with options setup
+
+go test -v -run Bench -benchtime 30s -bench Bench
+goos: linux
+goarch: amd64
+pkg: github.com/fredbi/uri
+cpu: AMD Ryzen 7 5800X 8-Core Processor             
+Benchmark_Parse
+Benchmark_Parse/with_URI_simple_payload
+Benchmark_Parse/with_URI_simple_payload-16         	137914446	       257.1 ns/op	       0 B/op	       0 allocs/op
+Benchmark_Parse/with_URL_simple_payload
+Benchmark_Parse/with_URL_simple_payload-16         	100000000	       319.7 ns/op	     168 B/op	       1 allocs/op
+Benchmark_Parse/with_URI_mixed_payload
+Benchmark_Parse/with_URI_mixed_payload-16          	138111548	       262.6 ns/op	       0 B/op	       0 allocs/op
+Benchmark_Parse/with_URL_mixed_payload
+Benchmark_Parse/with_URL_mixed_payload-16          	100000000	       302.5 ns/op	     163 B/op	       1 allocs/op
+Benchmark_Parse/with_URI_payload_with_IPs
+Benchmark_Parse/with_URI_payload_with_IPs-16       	128662461	       282.0 ns/op	       0 B/op	       0 allocs/op
+Benchmark_Parse/with_URL_payload_with_IPs
+Benchmark_Parse/with_URL_payload_with_IPs-16       	99240152	       365.3 ns/op	     176 B/op	       1 allocs/op
+Benchmark_String
+Benchmark_String-16                                	446582586	        80.53 ns/op	      48 B/op	       1 allocs/op
+Benchmark_DNSSchemes
+Benchmark_DNSSchemes/with_switch
+Benchmark_DNSSchemes/with_switch-16                	1000000000	         3.030 ns/op	       0 B/op	       0 allocs/op
+PASS
+
+

docs/TODO.md

@@ -13,8 +13,9 @@ v1.2
 * [x] fix scheme tolerance to be on ASCII only
 * [x] document the choice of a strict % escaping policy regarding char encoding (UTF8 mandatory)
 * [] handle empty fragment, empty query
+* [] fix scheme tolerance to be on ASCII only
 * [] IRI ucs charset compliance (att: perf challenge)
-- [] Support IRI iprivate in query
+* [] Support IRI iprivate in query
 * [] normalizer
 
 v2.0.0

go.mod

@@ -1,18 +1,18 @@
 module github.com/fredbi/uri
 
-go 1.20
+go 1.19
 
 require (
 	github.com/pkg/profile v1.7.0
 	github.com/stretchr/testify v1.8.4
 	golang.org/x/net v0.15.0
-	golang.org/x/text v0.13.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
 )