Add dsl.Randomiser that lets you pass your own example randomiser (goadesign#3191)

* Add dsl.Randomiser that lets you pass your own example randomiser

1. Rename `expr.Random` to `expr.FakerRandom`
2. Add an interface `expr.Randomiser` that covers the methods we need
3. Split out `expr.ExampleGenerator` that handles the 'do we already
   have an example for this' logic from the 'generate examples' stuff
4. Change `(expr.APIExpr).random` to `(expr.APIExpr).ExampleGenerator`,
   and initialise it with a faker-based random example generator
5. Add `dsl.Randomiser` which overrides `(expr.APIExpr).ExampleGenerator` with
   whatever randomiser you want to pass in, wrapped in the
   non-customisable 'only generate one example for each thing' logic.

I've also added an `ArrayLength` method to the randomiser interface, and
updated places that previously would call `r.Int()` to generate an array
length to use that.

The motivation for this PR is that we have a large design and many
people working on it, and the diffs we get on OpenAPI schema files can
be quite hard to read with most of the changes coming from changes to
the random examples due to the order of example generation when we add
new types (for example).

We'd therefore like to disable all random example generation and use
hard-coded default examples, and define manual examples with
`dsl.Example` where we'd like them.

* Randomiser -> Randomizer

* NewRandom -> NewFakerRandomizer and NewRandomExampleGenerator -> NewRandom

to maintain the existing interface

* Reorder the expr/random.go file to be clearer

* Rename FakerRandom -> FakerRandomizer

It implements `Randomizer`, so should really have that in its name

* Add DeterministicRandomizer, which returns hard-coded values

* Try to match the old randomization logic exactly

* Fix the openapi v2 tests

* remove spew

* Actually use `ArrayLength()`

I over-did it a bit in my effort to fix tests.

* Sort out the examples

Author: isaacseymour

codegen/service/service_data.go

@@ -912,7 +912,7 @@ func buildMethodData(m *expr.MethodExpr, scope *codegen.NameScope) *MethodData {
 			payloadDesc = fmt.Sprintf("%s is the payload type of the %s service %s method.",
 				payloadName, m.Service.Name, m.Name)
 		}
-		payloadEx = m.Payload.Example(expr.Root.API.Random())
+		payloadEx = m.Payload.Example(expr.Root.API.ExampleGenerator)
 	}
 	if m.Result.Type != expr.Empty {
 		rname = scope.GoTypeName(m.Result)
@@ -926,7 +926,7 @@ func buildMethodData(m *expr.MethodExpr, scope *codegen.NameScope) *MethodData {
 			resultDesc = fmt.Sprintf("%s is the result type of the %s service %s method.",
 				rname, m.Service.Name, m.Name)
 		}
-		resultEx = m.Result.Example(expr.Root.API.Random())
+		resultEx = m.Result.Example(expr.Root.API.ExampleGenerator)
 	}
 	if len(m.Errors) > 0 {
 		errors = make([]*ErrorInitData, len(m.Errors))
@@ -1002,7 +1002,7 @@ func initStreamData(data *MethodData, m *expr.MethodExpr, vname, rname, resultRe
 			spayloadDesc = fmt.Sprintf("%s is the streaming payload type of the %s service %s method.",
 				spayloadName, m.Service.Name, m.Name)
 		}
-		spayloadEx = m.StreamingPayload.Example(expr.Root.API.Random())
+		spayloadEx = m.StreamingPayload.Example(expr.Root.API.ExampleGenerator)
 	}
 	svrStream := &StreamData{
 		Interface:      vname + "ServerStream",

dsl/api.go

@@ -150,6 +150,38 @@ func License(fn func()) {
 	eval.IncompatibleDSL()
 }
 
+// Randomizer sets the API example randomizer.
+//
+// Randomizer must appear in a API expression.
+//
+// Randomizer takes a single argument which is an implementation of
+// expr.Randomizer.
+//
+// The default randomizer uses the API name as the seed, to get consistent
+// random examples.
+//
+// Example:
+//
+//    var _ = API("divider", func() {
+//        Randomizer(expr.NewFakerRandomizer("different seed"))
+//    })
+//
+// There's also a deterministic randomizer which will only generate one example
+// for each type, so all strings are "abc123", all ints are 1, etc.
+//
+// Example:
+//
+//    var _ = API("divider", func() {
+//        Randomizer(expr.NewDeterministicRandomizer())
+//    })
+func Randomizer(randomizer expr.Randomizer) {
+	if s, ok := eval.Current().(*expr.APIExpr); ok {
+		s.ExampleGenerator = &expr.ExampleGenerator{Randomizer: randomizer}
+		return
+	}
+	eval.IncompatibleDSL()
+}
+
 // Docs provides external documentation URLs. It is used by the generated
 // OpenAPI specification.
 //

expr/api.go

@@ -42,7 +42,7 @@ type (
 		GRPC *GRPCExpr
 
 		// random generator used to build examples for the API types.
-		random *Random
+		ExampleGenerator *ExampleGenerator
 	}
 
 	// ContactExpr contains the API contact information.
@@ -75,10 +75,11 @@ type (
 // NewAPIExpr initializes an API expression.
 func NewAPIExpr(name string, dsl func()) *APIExpr {
 	return &APIExpr{
-		Name:    name,
-		HTTP:    new(HTTPExpr),
-		GRPC:    new(GRPCExpr),
-		DSLFunc: dsl,
+		Name:             name,
+		HTTP:             new(HTTPExpr),
+		GRPC:             new(GRPCExpr),
+		DSLFunc:          dsl,
+		ExampleGenerator: NewRandom(name),
 	}
 }
 
@@ -102,15 +103,6 @@ func (a *APIExpr) Schemes() []string {
 	return ss
 }
 
-// Random returns the random generator associated with a. APIs with identical
-// names return generators that return the same sequence of pseudo random values.
-func (a *APIExpr) Random() *Random {
-	if a.random == nil {
-		a.random = NewRandom(a.Name)
-	}
-	return a.random
-}
-
 // DefaultServer returns a server expression that describes a server which
 // exposes all the services in the design and listens on localhost port 80 for
 // HTTP requests and port 8080 for gRPC requests.

expr/example.go

@@ -17,7 +17,7 @@ const (
 // Example returns the example set on the attribute at design time. If there
 // isn't such a value then Example computes a random value for the attribute
 // using the given random value producer.
-func (a *AttributeExpr) Example(r *Random) interface{} {
+func (a *AttributeExpr) Example(r *ExampleGenerator) interface{} {
 	if ex := a.ExtractUserExamples(); len(ex) > 0 {
 		// Return the last item in the slice so that examples can be overridden
 		// in the DSL. Overridden examples are always appended to the UserExamples
@@ -80,7 +80,7 @@ func (a *AttributeExpr) Example(r *Random) interface{} {
 
 // NewLength returns an int that validates the generator attribute length
 // validations if any.
-func NewLength(a *AttributeExpr, r *Random) int {
+func NewLength(a *AttributeExpr, r *ExampleGenerator) int {
 	if hasLengthValidation(a) {
 		minlength, maxlength := math.Inf(1), math.Inf(-1)
 		if a.Validation.MinLength != nil {
@@ -110,7 +110,7 @@ func NewLength(a *AttributeExpr, r *Random) int {
 		}
 		return count
 	}
-	return r.Int()%3 + 2
+	return r.ArrayLength()
 }
 
 func hasLengthValidation(a *AttributeExpr) bool {
@@ -143,13 +143,13 @@ func hasMinMaxValidation(a *AttributeExpr) bool {
 }
 
 // byLength generates a random size array of examples based on what's given.
-func byLength(a *AttributeExpr, r *Random) interface{} {
+func byLength(a *AttributeExpr, r *ExampleGenerator) interface{} {
 	count := NewLength(a, r)
 	switch a.Type.Kind() {
 	case StringKind:
-		return r.faker.Characters(count)
+		return r.Characters(count)
 	case BytesKind:
-		return []byte(r.faker.Characters(count))
+		return []byte(r.Characters(count))
 	case MapKind:
 		raw := make(map[interface{}]interface{})
 		m := a.Type.(*Map)
@@ -170,7 +170,7 @@ func byLength(a *AttributeExpr, r *Random) interface{} {
 }
 
 // byEnum returns a random selected enum value.
-func byEnum(a *AttributeExpr, r *Random) interface{} {
+func byEnum(a *AttributeExpr, r *ExampleGenerator) interface{} {
 	if !hasEnumValidation(a) {
 		return nil
 	}
@@ -181,20 +181,20 @@ func byEnum(a *AttributeExpr, r *Random) interface{} {
 }
 
 // byFormat returns a random example based on the format the user asks.
-func byFormat(a *AttributeExpr, r *Random) interface{} {
+func byFormat(a *AttributeExpr, r *ExampleGenerator) interface{} {
 	if !hasFormatValidation(a) {
 		return nil
 	}
 	format := a.Validation.Format
 	if res, ok := map[ValidationFormat]interface{}{
-		FormatEmail:    r.faker.Email(),
-		FormatHostname: r.faker.DomainName() + "." + r.faker.DomainSuffix(),
+		FormatEmail:    r.Email(),
+		FormatHostname: r.Hostname(),
 		FormatDate:     time.Unix(int64(r.Int())%1454957045, 0).UTC().Format("2006-01-02"), // to obtain a "fixed" rand
 		FormatDateTime: time.Unix(int64(r.Int())%1454957045, 0).UTC().Format(time.RFC3339), // to obtain a "fixed" rand
-		FormatIPv4:     r.faker.IPv4Address().String(),
-		FormatIPv6:     r.faker.IPv6Address().String(),
-		FormatIP:       r.faker.IPv4Address().String(),
-		FormatURI:      r.faker.URL(),
+		FormatIPv4:     r.IPv4Address().String(),
+		FormatIPv6:     r.IPv6Address().String(),
+		FormatIP:       r.IPv4Address().String(),
+		FormatURI:      r.URL(),
 		FormatMAC: func() string {
 			res, err := regen.Generate(`([0-9A-F]{2}-){5}[0-9A-F]{2}`)
 			if err != nil {
@@ -203,7 +203,7 @@ func byFormat(a *AttributeExpr, r *Random) interface{} {
 			return res
 		}(),
 		FormatCIDR:    "192.168.100.14/24",
-		FormatRegexp:  r.faker.Characters(3) + ".*",
+		FormatRegexp:  r.Characters(3) + ".*",
 		FormatRFC1123: time.Unix(int64(r.Int())%1454957045, 0).UTC().Format(time.RFC1123), // to obtain a "fixed" rand
 		FormatUUID: func() string {
 			res, err := regen.Generate(`[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}`)
@@ -222,19 +222,19 @@ func byFormat(a *AttributeExpr, r *Random) interface{} {
 // byPattern generates a random value that satisfies the pattern.
 //
 // Note: if multiple patterns are given, only one of them is used.
-func byPattern(a *AttributeExpr, r *Random) interface{} {
+func byPattern(a *AttributeExpr, r *ExampleGenerator) interface{} {
 	if !hasPatternValidation(a) {
 		return false
 	}
 	pattern := a.Validation.Pattern
 	gen, err := regen.NewGenerator(pattern, &regen.GeneratorArgs{MaxUnboundedRepeatCount: 6})
 	if err != nil {
-		return r.faker.Name()
+		return r.Name()
 	}
 	return gen.Generate()
 }
 
-func byMinMax(a *AttributeExpr, r *Random) interface{} {
+func byMinMax(a *AttributeExpr, r *ExampleGenerator) interface{} {
 	if !hasMinMaxValidation(a) {
 		return nil
 	}