From 0a1938f07d30e047de238ff7711f720be5561682 Mon Sep 17 00:00:00 2001
From: Bojan <dbojan@gmail.com>
Date: Sun, 25 Oct 2020 17:02:14 -0300
Subject: [PATCH] add call data docs and clean up code

---
 runner/{call_template_data.go => calldata.go} |  4 +--
 ...template_data_test.go => calldata_test.go} |  6 ++--
 runner/options.go                             |  7 ++++-
 www/docs/calldata.md                          | 29 ++++++++++++++++---
 4 files changed, 36 insertions(+), 10 deletions(-)
 rename runner/{call_template_data.go => calldata.go} (97%)
 rename runner/{call_template_data_test.go => calldata_test.go} (98%)

diff --git a/runner/call_template_data.go b/runner/calldata.go
similarity index 97%
rename from runner/call_template_data.go
rename to runner/calldata.go
index 0656fe6b..b7c2320a 100644
--- a/runner/call_template_data.go
+++ b/runner/calldata.go
@@ -17,7 +17,7 @@ const charset = "abcdefghijklmnopqrstuvwxyz" +
 var seededRand *rand.Rand = rand.New(
 	rand.NewSource(time.Now().UnixNano()))
 
-// call template data
+// CallData represents contextualized data available for templating
 type CallData struct {
 	WorkerID           string // unique worker ID
 	RequestNumber      int64  // unique incremented request number for each request
@@ -42,7 +42,7 @@ var tmplFuncMap = template.FuncMap{
 	"randomString": randomString,
 }
 
-// newCallData returns new callData
+// newCallData returns new CallData
 func newCallData(
 	mtd *desc.MethodDescriptor,
 	funcs template.FuncMap,
diff --git a/runner/call_template_data_test.go b/runner/calldata_test.go
similarity index 98%
rename from runner/call_template_data_test.go
rename to runner/calldata_test.go
index bdf2897d..db416c3f 100644
--- a/runner/call_template_data_test.go
+++ b/runner/calldata_test.go
@@ -10,7 +10,7 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
-func TestCallTemplateData_New(t *testing.T) {
+func TestCallData_New(t *testing.T) {
 	md, err := protodesc.GetMethodDescFromProto("helloworld.Greeter/SayHello", "../testdata/greeter.proto", []string{})
 	assert.NoError(t, err)
 	assert.NotNil(t, md)
@@ -36,7 +36,7 @@ func TestCallTemplateData_New(t *testing.T) {
 	assert.Equal(t, 36, len(ctd.UUID))
 }
 
-func TestCallTemplateData_ExecuteData(t *testing.T) {
+func TestCallData_ExecuteData(t *testing.T) {
 	md, err := protodesc.GetMethodDescFromProto("helloworld.Greeter/SayHello", "../testdata/greeter.proto", []string{})
 	assert.NoError(t, err)
 	assert.NotNil(t, md)
@@ -87,7 +87,7 @@ func TestCallTemplateData_ExecuteData(t *testing.T) {
 	}
 }
 
-func TestCallTemplateData_ExecuteMetadata(t *testing.T) {
+func TestCallData_ExecuteMetadata(t *testing.T) {
 	md, err := protodesc.GetMethodDescFromProto("helloworld.Greeter/SayHello", "../testdata/greeter.proto", []string{})
 	assert.NoError(t, err)
 	assert.NotNil(t, md)
diff --git a/runner/options.go b/runner/options.go
index 9a73e77b..1778fb8e 100644
--- a/runner/options.go
+++ b/runner/options.go
@@ -20,6 +20,11 @@ import (
 	"google.golang.org/grpc/credentials"
 )
 
+// BinaryDataFunc is a function that can be used for provide binary data for request programatically.
+// MethodDescriptor of the call is passed to the data function.
+// CallData for the request is passed and can be used to access worker id, request number, etc...
+type BinaryDataFunc func(mtd *desc.MethodDescriptor, callData *CallData) []byte
+
 // RunConfig represents the request Configs
 type RunConfig struct {
 	// call settings
@@ -62,7 +67,7 @@ type RunConfig struct {
 	data []byte
 
 	// data func
-	dataFunc func(mtd *desc.MethodDescriptor, callData *CallData) []byte
+	dataFunc BinaryDataFunc
 
 	binary   bool
 	metadata []byte
diff --git a/www/docs/calldata.md b/www/docs/calldata.md
index 6ee7cc23..9c1e324e 100644
--- a/www/docs/calldata.md
+++ b/www/docs/calldata.md
@@ -1,13 +1,13 @@
 ---
 id: calldata
-title: Call Template Data
+title: Call Data
 ---
 
 Data and metadata can specify [template actions](https://golang.org/pkg/text/template/) that will be parsed and evaluated at every request. Each request gets a new instance of the data. The available variables / actions are:
 
 ```go
-// call template data
-type callTemplateData struct {
+// CallData represents contextualized data available for templating
+type CallData struct {
 
 	// unique worker ID
 	WorkerID		   string
@@ -53,7 +53,7 @@ type callTemplateData struct {
 }
 ```
 
-**Functions**
+**Template Functions**
 
 There are also two template functions available:
 
@@ -95,3 +95,24 @@ Would result in data with JSON representation:
 ```
 
 See [example calls](examples.md) for some more usage examples.
+
+### Data Function API
+
+When using the `ghz/runner` package programmatically, we can dynamically create data for each request using `WithBinaryDataFunc()` API:
+
+```go
+func dataFunc(mtd *desc.MethodDescriptor, cd *runner.CallData) []byte {
+	msg := &helloworld.HelloRequest{}
+	msg.Name = cd.WorkerID
+	binData, err := proto.Marshal(msg)
+	return binData
+}
+
+report, err := runner.Run(
+	"helloworld.Greeter.SayHello",
+	"0.0.0.0:50051",
+	runner.WithProtoFile("./testdata/greeter.proto", []string{}),
+	runner.WithInsecure(true),
+	runner.WithBinaryDataFunc(dataFunc),
+)
+```