Merge pull request #121 from speakeasy-api/walker/go-sdk-render-accessors

Replace Guide.Render with RenderExternal and RenderSpeakeasy [minor]

Author: walker-tx

go/README.md

@@ -36,27 +36,27 @@ func main() {
 
 ## Rendering the callback URL
 
-Guide content ships with the template key `{{ gram.oauth.callback_url }}`
-in place. Pass your own value on every lookup to substitute it:
+`Guide.External` and `Guide.Speakeasy` ship with the template key
+`{{ gram.oauth.callback_url }}` in place. **Serve the renderers, not the raw
+fields.** Pass your own value on every call:
 
 ```go
-g, _ := guides.Lookup("intercom")
+vars := guides.Vars{OAuthCallbackURL: "https://app.example.com/oauth/callback"}
 
-g = g.Render(guides.Vars{
-	OAuthCallbackURL: "https://app.example.com/oauth/callback",
-})
-os.Stdout.Write(g.External)
+g, _ := guides.Lookup("intercom")
+os.Stdout.Write(g.RenderExternal(vars))
 ```
 
-- `Render` returns a **copy**. It never changes the embedded content, so a
-  server may render per request with a different value each time.
+- The renderers never change the embedded content, so a server may render per
+  request with a different value each time. **Treat the result as read-only:**
+  an empty `Vars` returns a slice aliasing the raw field.
 - The callback URL is a property of your deployment, not of the guide, so
-  there is nothing to look up first. A guide that never references the key
+  there is nothing to look up first. Content that never references the key
   comes back unchanged.
 - An empty `Vars` field leaves its key in place, so a missing value degrades
-  to the unrendered guide instead of a blank.
-- `Render` substitutes `External` and `Speakeasy` only. No template key
-  reaches `Meta` or an asset — the generator fails if one ever does.
+  to the unrendered content instead of a blank.
+- Only `External` and `Speakeasy` have a renderer. No template key reaches
+  `Meta` or an asset — the generator fails if one ever does.
 - `{{ gram.oauth.callback_url }}` is the only supported key. Add a field to
   `Vars` to support another; existing callers keep compiling.
 

go/doc.go

@@ -6,11 +6,12 @@
 // secondary indexes that may return zero, one, or many matches; they never
 // invent a default remote.
 //
-// Guide content ships with the template key {{ gram.oauth.callback_url }}
-// in place. Guide.Render(Vars) returns a copy with a caller-supplied value
-// substituted. Supply the value on every call: it is a property of the
-// deployment, not of the guide, and a guide that never references the key
-// comes back unchanged.
+// Guide.External and Guide.Speakeasy ship with the template key
+// {{ gram.oauth.callback_url }} in place. Serve Guide.RenderExternal(Vars)
+// and Guide.RenderSpeakeasy(Vars) instead: they return the same content
+// with a caller-supplied value substituted. Supply the value on every call.
+// It is a property of the deployment, not of the guide, and content that
+// never references the key comes back unchanged.
 //
 // Module path: github.com/speakeasy-api/mcp-setup-docs/go
 // Version tags: go/vX.Y.Z

go/guides_test.go

@@ -433,65 +433,61 @@ func TestQueryMechanisms(t *testing.T) {
 	})
 }
 
-// A caller supplies the callback URL on every Render, so run the whole
-// corpus through one call: no guide may keep the key, and a guide that
-// never carried it must come back byte-identical.
+// A caller supplies the callback URL on every render, so run both
+// renderers over the whole corpus: no output may keep the key, and content
+// that never carried it must come back byte-identical.
 func TestRenderSubstitutesEveryKey(t *testing.T) {
 	const callback = "https://app.example.com/oauth/callback"
 	key := []byte(canonicalCallbackKey)
+	vars := guides.Vars{OAuthCallbackURL: callback}
 	substituted := 0
-	for _, g := range guides.Guides() {
-		hadKey := bytes.Contains(g.External, key) || bytes.Contains(g.Speakeasy, key)
-		out := g.Render(guides.Vars{OAuthCallbackURL: callback})
-
-		if bytes.Contains(out.External, key) || bytes.Contains(out.Speakeasy, key) {
-			t.Errorf("%s: content still carries the key after Render", g.Slug)
+	check := func(slug guides.GuideSlug, field string, raw, out []byte) {
+		if bytes.Contains(out, key) {
+			t.Errorf("%s %s: output still carries the key", slug, field)
 		}
-		if !bytes.Equal(out.Meta, g.Meta) {
-			t.Errorf("%s: Render must not touch Meta", g.Slug)
-		}
-
-		if !hadKey {
-			if !bytes.Equal(out.External, g.External) || !bytes.Equal(out.Speakeasy, g.Speakeasy) {
-				t.Errorf("%s: Render changed a guide that carries no key", g.Slug)
+		if !bytes.Contains(raw, key) {
+			if !bytes.Equal(out, raw) {
+				t.Errorf("%s %s: content with no key changed", slug, field)
 			}
-			continue
+			return
 		}
 		substituted++
-		if !bytes.Contains(out.External, []byte(callback)) &&
-			!bytes.Contains(out.Speakeasy, []byte(callback)) {
-			t.Errorf("%s: Render substituted nothing", g.Slug)
+		if !bytes.Contains(out, []byte(callback)) {
+			t.Errorf("%s %s: substituted nothing", slug, field)
 		}
 	}
+	for _, g := range guides.Guides() {
+		check(g.Slug, "External", g.External, g.RenderExternal(vars))
+		check(g.Slug, "Speakeasy", g.Speakeasy, g.RenderSpeakeasy(vars))
+	}
 	if substituted == 0 {
 		t.Fatal("no guide carries the key; the matrix would be vacuous")
 	}
 }
 
-// A missing value must degrade to the unrendered guide, never to a blank
+// A missing value must degrade to the unrendered content, never to a blank
 // where the URL belongs.
 func TestRenderLeavesKeyWhenValueEmpty(t *testing.T) {
 	g, ok := guides.Lookup("intercom")
 	if !ok {
 		t.Fatal("intercom missing")
 	}
-	out := g.Render(guides.Vars{})
-	if !bytes.Contains(out.External, []byte(canonicalCallbackKey)) {
+	if !bytes.Contains(g.RenderExternal(guides.Vars{}), []byte(canonicalCallbackKey)) {
 		t.Error("empty Vars must leave the template key in place")
 	}
 }
 
-// The embedded bytes back every future Lookup, so rendering one copy must
-// not reach them. A caller that renders per request depends on this.
+// The embedded bytes back every future Lookup, so rendering must not reach
+// them. A caller that renders per request depends on this.
 func TestRenderDoesNotDisturbEmbeddedContent(t *testing.T) {
 	g, ok := guides.Lookup("intercom")
 	if !ok {
 		t.Fatal("intercom missing")
 	}
 	before := string(g.External)
-	_ = g.Render(guides.Vars{OAuthCallbackURL: "https://app.example.com/cb"})
+	_ = g.RenderExternal(guides.Vars{OAuthCallbackURL: "https://app.example.com/cb"})
 	if string(g.External) != before {
-		t.Error("Render mutated the Guide it was called on")
+		t.Error("a renderer changed the Guide it was called on")
 	}
 	again, ok := guides.Lookup("intercom")
 	if !ok {

go/internal/gen/main.go

@@ -29,7 +29,8 @@ const canonicalCallbackKey = "{{ gram.oauth.callback_url }}"
 
 // templateKeyPattern finds every "{{ … }}" span, including malformed
 // spacing, so a non-canonical key fails generation instead of shipping
-// unrendered. This check is what lets Render match one exact byte string.
+// unrendered. This check is what lets the renderers match one exact byte
+// string.
 var templateKeyPattern = regexp.MustCompile(`\{\{[^{}]*\}\}`)
 
 type assetMeta struct {
@@ -417,9 +418,9 @@ func run() error {
 }
 
 // scanTemplateKeys enforces the single-template-key rule. One canonical
-// spelling is what lets Guide.Render substitute with a plain byte replace
-// instead of a regexp. metaRaw must carry no key at all: Render substitutes
-// only External and Speakeasy, so a key in meta.yaml would ship to a reader
+// spelling is what lets package guides substitute with a plain byte replace
+// instead of a regexp. metaRaw must carry no key at all: only External and
+// Speakeasy have a renderer, so a key in meta.yaml would ship to a reader
 // unrendered.
 func scanTemplateKeys(slug, srcDir string, metaRaw []byte) error {
 	if key := templateKeyPattern.Find(metaRaw); key != nil {

go/internal/gen/main_test.go

@@ -251,8 +251,8 @@ remotes:
 }
 
 // The generator is the only place that enforces the one-key rule, so the
-// rejections matter as much as the happy path: Render substitutes with a
-// literal byte replacement on the strength of this check.
+// rejections matter as much as the happy path: the renderers substitute
+// with a literal byte replacement on the strength of this check.
 func TestScanTemplateKeys(t *testing.T) {
 	for _, tc := range []struct {
 		name      string

go/render.go

@@ -13,27 +13,27 @@ type Vars struct {
 	// Speakeasy AI Control Plane callback URL that the reader registers
 	// in the provider's redirect field.
 	//
-	// Supply it on every Render call. It is a property of the deployment,
-	// not of the guide, so there is nothing to look up first: guides that
-	// never reference it come back unchanged.
+	// Supply it on every call. It is a property of the deployment, not of
+	// the guide, so there is nothing to look up first: content that never
+	// references it comes back unchanged.
 	//
 	// An empty value leaves the key in the content rather than blanking
-	// it, so a missing value degrades to the unrendered guide.
+	// it, so a missing value degrades to the unrendered content.
 	OAuthCallbackURL string
 }
 
-// Render returns a copy of g whose External and Speakeasy content has the
-// template keys replaced by the values in v. Meta, Assets, and every
-// identity field are unchanged — no template key appears in meta.yaml or
-// in an asset, and the generator fails if one ever does.
-//
-// Render never changes the embedded content. Each Lookup starts from the
-// unrendered bytes, and rendering one copy does not affect another.
-func (g Guide) Render(v Vars) Guide {
-	if v.OAuthCallbackURL != "" {
-		value := []byte(v.OAuthCallbackURL)
-		g.External = bytes.ReplaceAll(g.External, callbackURLKey, value)
-		g.Speakeasy = bytes.ReplaceAll(g.Speakeasy, callbackURLKey, value)
+// RenderExternal returns External with the template keys replaced by the
+// values in v. Serve this rather than the raw field: the raw field still
+// carries the keys. Treat the result as read-only; it may alias External.
+func (g Guide) RenderExternal(v Vars) []byte { return render(g.External, v) }
+
+// RenderSpeakeasy returns Speakeasy with the template keys replaced. See
+// RenderExternal.
+func (g Guide) RenderSpeakeasy(v Vars) []byte { return render(g.Speakeasy, v) }
+
+func render(content []byte, v Vars) []byte {
+	if v.OAuthCallbackURL == "" {
+		return content
 	}
-	return g
+	return bytes.ReplaceAll(content, callbackURLKey, []byte(v.OAuthCallbackURL))
 }