@shortlink-org/portolan 0.1.0

package/plugins/extract-go/httpclient.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"go/ast"
+	"go/token"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/shortlink-org/portolan/plugins/openapi"
+)
+
+// An HTTP client generated by oapi-codegen is read the way a gRPC client is:
+// the tree already says which route each method calls. `New<Op>Request` builds
+// the request, and its body names the path and the verb; the document the
+// client was generated from is vendored beside it, and says which operation
+// answers on that route and which interface it belongs to. Put together, a
+// call on the client is `auth.v1.Sessions/login` - the same id the OpenAPI
+// extractor gives the method on the other side, because both spell it with
+// the same package.
+
+// The four names a generated client is held by in a use case or an adapter.
+var httpClientTypes = []string{"Client", "ClientInterface", "ClientWithResponses", "ClientWithResponsesInterface"}
+
+// isHTTPClient says whether a package is one oapi-codegen generated a client
+// into: a ClientInterface and at least one request builder.
+func isHTTPClient(p *pkg) bool {
+	var iface, builder bool
+	for _, file := range p.files {
+		for _, decl := range file.Decls {
+			switch d := decl.(type) {
+			case *ast.GenDecl:
+				for _, spec := range d.Specs {
+					if ts, ok := spec.(*ast.TypeSpec); ok && ts.Name.Name == "ClientInterface" {
+						if _, ok := ts.Type.(*ast.InterfaceType); ok {
+							iface = true
+						}
+					}
+				}
+			case *ast.FuncDecl:
+				if d.Recv == nil && requestBuilderOp(d.Name.Name) != "" {
+					builder = true
+				}
+			}
+		}
+	}
+
+	return iface && builder
+}
+
+// requestBuilderOp reads the operation's Go name off a request builder:
+// NewLoginRequest and NewLoginRequestWithBody are both Login.
+func requestBuilderOp(name string) string {
+	rest, ok := strings.CutPrefix(name, "New")
+	if !ok {
+		return ""
+	}
+	if op, ok := strings.CutSuffix(rest, "RequestWithBody"); ok {
+		return op
+	}
+	if op, ok := strings.CutSuffix(rest, "Request"); ok {
+		return op
+	}
+
+	return ""
+}
+
+// readHTTPClient reads the routes the generated client calls and names them
+// by the vendored document. The problem, when there is one, is a sentence
+// for the reader of the diagnostics: no document beside the client, or a
+// route the document does not declare.
+func readHTTPClient(p *pkg) (map[string]client, string) {
+	spec, source, problem := specBeside(p)
+	if problem != "" {
+		return nil, problem
+	}
+
+	c := client{pkg: spec.API, methods: map[string]string{}, source: source, external: openapi.ExternalID(spec.Title)}
+	var unknown []string
+	for _, file := range p.files {
+		for _, decl := range file.Decls {
+			fn, ok := decl.(*ast.FuncDecl)
+			if !ok || fn.Recv != nil {
+				continue
+			}
+			op := requestBuilderOp(fn.Name.Name)
+			if op == "" {
+				continue
+			}
+			verb, path := routeOf(fn)
+			if verb == "" || path == "" {
+				continue
+			}
+			found, ok := spec.Find(verb, path)
+			if !ok {
+				unknown = append(unknown, verb+" "+path)
+
+				continue
+			}
+			id := found.CallID(spec.API)
+			// Every way the client offers the operation, to the same call.
+			for _, variant := range []string{op, op + "WithBody", op + "WithResponse", op + "WithBodyWithResponse"} {
+				c.methods[variant] = id
+			}
+		}
+	}
+
+	out := map[string]client{}
+	for _, name := range httpClientTypes {
+		out[name] = c
+	}
+	if len(unknown) > 0 {
+		return out, "the client in " + p.dir + " calls " + strings.Join(unknown, ", ") + ", which the document beside it does not declare; those calls are left out"
+	}
+
+	return out, ""
+}
+
+// specBeside finds the document the client was generated from, in the same
+// directory, and reads it.
+func specBeside(p *pkg) (*openapi.Spec, string, string) {
+	for _, name := range []string{"openapi.yaml", "openapi.yml", "swagger.yaml", "swagger.yml"} {
+		path := filepath.Join(filepath.FromSlash(p.dir), name)
+		if _, err := os.Stat(path); err != nil {
+			continue
+		}
+		spec, err := openapi.Read(path)
+		if err != nil {
+			return nil, "", err.Error()
+		}
+
+		return spec, filepath.ToSlash(path), ""
+	}
+
+	return nil, "", "the client in " + p.dir + " has no openapi document beside it, so its calls cannot be named; vendor the document the client was generated from"
+}
+
+// routeOf reads the verb and path out of a request builder's body:
+//
+//	operationPath := fmt.Sprintf("/v1/users/%s", pathParam0)
+//	req, err := http.NewRequest(http.MethodGet, queryURL.String(), nil)
+func routeOf(fn *ast.FuncDecl) (verb, path string) {
+	ast.Inspect(fn.Body, func(node ast.Node) bool {
+		switch n := node.(type) {
+		case *ast.AssignStmt:
+			if len(n.Lhs) == 1 && len(n.Rhs) == 1 {
+				if ident, ok := n.Lhs[0].(*ast.Ident); ok && ident.Name == "operationPath" {
+					if call, ok := n.Rhs[0].(*ast.CallExpr); ok && len(call.Args) > 0 {
+						if lit, ok := call.Args[0].(*ast.BasicLit); ok && lit.Kind == token.STRING {
+							path, _ = strconv.Unquote(lit.Value)
+						}
+					}
+				}
+			}
+		case *ast.CallExpr:
+			if sel, ok := n.Fun.(*ast.SelectorExpr); ok && sel.Sel.Name == "NewRequest" && len(n.Args) > 0 {
+				switch arg := n.Args[0].(type) {
+				case *ast.SelectorExpr:
+					// http.MethodPost
+					verb = strings.ToUpper(strings.TrimPrefix(arg.Sel.Name, "Method"))
+				case *ast.BasicLit:
+					if s, err := strconv.Unquote(arg.Value); err == nil {
+						verb = strings.ToUpper(s)
+					}
+				}
+			}
+		}
+
+		return true
+	})
+
+	return verb, path
+}

package/plugins/extract-go/httpclient_test.go

@@ -0,0 +1,296 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// The shape oapi-codegen v2 generates, cut to what the reader looks at: the
+// interface, and the request builders with their route.
+const generatedHTTPClient = `package gen
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+)
+
+type ClientInterface interface {
+	LoginWithBody(ctx context.Context, contentType string, body io.Reader, reqEditors ...RequestEditorFn) (*http.Response, error)
+	Login(ctx context.Context, body LoginJSONRequestBody, reqEditors ...RequestEditorFn) (*http.Response, error)
+	GetUser(ctx context.Context, userId string, reqEditors ...RequestEditorFn) (*http.Response, error)
+}
+
+type ClientWithResponsesInterface interface {
+	LoginWithResponse(ctx context.Context, body LoginJSONRequestBody, reqEditors ...RequestEditorFn) (*LoginResponse, error)
+	GetUserWithResponse(ctx context.Context, userId string, reqEditors ...RequestEditorFn) (*GetUserResponse, error)
+}
+
+type ClientWithResponses struct{ ClientInterface }
+
+func NewLoginRequest(server string, body LoginJSONRequestBody) (*http.Request, error) {
+	return NewLoginRequestWithBody(server, "application/json", nil)
+}
+
+func NewLoginRequestWithBody(server string, contentType string, body io.Reader) (*http.Request, error) {
+	operationPath := fmt.Sprintf("/v1/sessions")
+	req, err := http.NewRequest(http.MethodPost, server+operationPath, body)
+	return req, err
+}
+
+func NewGetUserRequest(server string, userId string) (*http.Request, error) {
+	pathParam0 := userId
+	operationPath := fmt.Sprintf("/v1/users/%s", pathParam0)
+	req, err := http.NewRequest("GET", server+operationPath, nil)
+	return req, err
+}
+
+func NewPingRequest(server string) (*http.Request, error) {
+	operationPath := fmt.Sprintf("/v1/ping")
+	req, err := http.NewRequest(http.MethodGet, server+operationPath, nil)
+	return req, err
+}
+`
+
+const vendoredSpec = `openapi: 3.0.3
+info:
+  title: auth
+  version: 1.0.0
+paths:
+  /v1/sessions:
+    post:
+      operationId: login
+      tags: [sessions]
+  /v1/users/{userId}:
+    get:
+      operationId: getUser
+      tags: [users]
+`
+
+func writeTree(t *testing.T, root string, files map[string]string) {
+	t.Helper()
+	for rel, contents := range files {
+		if err := os.MkdirAll(filepath.Dir(filepath.Join(root, rel)), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(root, rel), []byte(contents), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+// The route is read off the request builder and named by the document
+// beside it, and every way the client offers the operation is the same call.
+func TestAnHTTPClientIsNamedByTheDocumentBesideIt(t *testing.T) {
+	root := t.TempDir()
+	writeTree(t, root, map[string]string{
+		"internal/infrastructure/auth/gen/client.gen.go": generatedHTTPClient,
+		"internal/infrastructure/auth/gen/openapi.yaml":  vendoredSpec,
+	})
+	pkg, err := parsePkg(root, "internal/infrastructure/auth/gen")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	clients, problem := readClients(pkg)
+	if !strings.Contains(problem, "GET /v1/ping") {
+		t.Errorf("a route the document does not declare should be reported: %q", problem)
+	}
+	c, ok := clients["ClientWithResponsesInterface"]
+	if !ok || c.pkg != "auth.v1" {
+		t.Fatalf("clients = %+v", clients)
+	}
+	for _, name := range httpClientTypes {
+		if _, ok := clients[name]; !ok {
+			t.Errorf("no client under %s", name)
+		}
+	}
+	want := map[string]string{
+		"Login":                       "auth.v1/login",
+		"LoginWithBody":               "auth.v1/login",
+		"LoginWithResponse":           "auth.v1/login",
+		"GetUserWithResponse":         "auth.v1/getUser",
+		"GetUser":                     "auth.v1/getUser",
+		"GetUserWithBodyWithResponse": "auth.v1/getUser",
+	}
+	for method, id := range want {
+		if c.methods[method] != id {
+			t.Errorf("%s = %q, want %q", method, c.methods[method], id)
+		}
+	}
+	if _, named := c.methods["Ping"]; named {
+		t.Error("a route the document does not declare was given a name")
+	}
+	if !strings.HasSuffix(c.source, "openapi.yaml") {
+		t.Errorf("source = %q, want the document", c.source)
+	}
+}
+
+// Without the document the client cannot be named, and the reader says so
+// rather than inventing an id from the route.
+func TestAnHTTPClientWithoutItsDocumentIsReported(t *testing.T) {
+	root := t.TempDir()
+	writeTree(t, root, map[string]string{
+		"internal/infrastructure/auth/gen/client.gen.go": generatedHTTPClient,
+	})
+	pkg, err := parsePkg(root, "internal/infrastructure/auth/gen")
+	if err != nil {
+		t.Fatal(err)
+	}
+	clients, problem := readClients(pkg)
+	if len(clients) != 0 || !strings.Contains(problem, "no openapi document beside it") {
+		t.Errorf("clients = %v, problem = %q", clients, problem)
+	}
+}
+
+// The whole chain over HTTP: a use case holds the generated client as a
+// port, and a call on it is an rpc to the service the manifest names for the
+// api, with the call on the service's consumes.
+func TestAUseCaseCallingAnHTTPClientIsAnRpcHop(t *testing.T) {
+	root := t.TempDir()
+	writeTree(t, root, map[string]string{
+		"go.mod": "module github.com/example/gateway\n\ngo 1.27\n",
+		"internal/infrastructure/auth/gen/client.gen.go": generatedHTTPClient,
+		"internal/infrastructure/auth/gen/openapi.yaml":  vendoredSpec,
+		"internal/application/session/usecases/whoami/usecase.go": `package whoami
+
+import (
+	"context"
+
+	"github.com/example/gateway/internal/infrastructure/auth/gen"
+)
+
+type UseCase struct {
+	auth gen.ClientWithResponsesInterface
+}
+
+func (uc *UseCase) Handle(ctx context.Context, in dto.Input) (dto.Output, error) {
+	resp, err := uc.auth.GetUserWithResponse(ctx, in.UserID)
+	if err != nil {
+		return dto.Output{}, err
+	}
+	switch resp.StatusCode() {
+	case 200:
+		_, err := uc.auth.LoginWithResponse(ctx, gen.LoginJSONRequestBody{})
+		return dto.Output{}, err
+	case 401, 403:
+		return dto.Output{}, ErrRefused
+	}
+	return dto.Output{}, nil
+}
+`,
+	})
+
+	b := &plugin.Builder{}
+	r := newFlowReader(root, flowOptions{context: "edge", svcID: "edge.gateway", service: "gateway", peers: map[string]string{"auth.v1": "auth.auth"}}, b)
+	d := newDraft()
+	d.lane(r.serviceLane())
+	r.walkUseCase(d, "session/whoami", 0)
+
+	if got := dump(d.steps); got != "s1:getUser alt3{s2:login } " {
+		t.Fatalf("nodes = %q", got)
+	}
+	first := d.steps[0].(*catalog.Step)
+	if first.Kind != catalog.StepRPC || first.To != "auth.auth" || first.Ref != "auth.v1/getUser" || first.Status != catalog.StatusDeclared {
+		t.Errorf("first = %+v", first)
+	}
+	alt := d.steps[1].(*catalog.Alt)
+	titles := []string{}
+	for _, br := range alt.Branches {
+		titles = append(titles, br.Title)
+	}
+	if strings.Join(titles, "|") != "resp.StatusCode() is 200|resp.StatusCode() is 401, 403|otherwise" {
+		t.Errorf("titles = %q", titles)
+	}
+	if !alt.Branches[0].Terminal || !alt.Branches[1].Terminal || alt.Branches[2].Terminal {
+		t.Errorf("terminal marks = %v %v %v", alt.Branches[0].Terminal, alt.Branches[1].Terminal, alt.Branches[2].Terminal)
+	}
+	calls := r.consumes()
+	if len(calls) != 2 || calls[0].ID != "auth.v1/getUser" || calls[1].ID != "auth.v1/login" || calls[0].Peer != "auth.auth" {
+		t.Errorf("consumes = %+v", calls)
+	}
+	for _, diag := range b.Response().Warnings() {
+		if strings.Contains(diag.Message, "/v1/ping") {
+			continue
+		}
+		t.Errorf("unexpected diagnostic: %s", diag.Message)
+	}
+}
+
+// A generated HTTP client whose api no peers line claims calls the system its
+// vendored document is titled after: a service that vendors a document and
+// generates a client from it is calling whatever that document describes, and
+// nothing in this tree implements it. The manifest may still name the system
+// itself, under externals, and then that name wins.
+func TestAnHTTPClientNobodyClaimsCallsTheSystemItsDocumentIsTitledAfter(t *testing.T) {
+	partnerSpec := strings.Replace(vendoredSpec, "title: auth", "title: Partner Booking API", 1)
+	useCase := `package whoami
+
+import (
+	"context"
+
+	"github.com/example/gateway/internal/infrastructure/partner/gen"
+)
+
+type UseCase struct {
+	partner gen.ClientWithResponsesInterface
+}
+
+func (uc *UseCase) Handle(ctx context.Context, in dto.Input) (dto.Output, error) {
+	_, err := uc.partner.GetUserWithResponse(ctx, in.UserID)
+	return dto.Output{}, err
+}
+`
+	tree := map[string]string{
+		"go.mod": "module github.com/example/gateway\n\ngo 1.27\n",
+		"internal/infrastructure/partner/gen/client.gen.go":       generatedHTTPClient,
+		"internal/infrastructure/partner/gen/openapi.yaml":        partnerSpec,
+		"internal/application/session/usecases/whoami/usecase.go": useCase,
+	}
+
+	read := func(opts flowOptions) (*catalog.Step, []catalog.RpcCall, *plugin.Builder) {
+		t.Helper()
+		root := t.TempDir()
+		writeTree(t, root, tree)
+		b := &plugin.Builder{}
+		r := newFlowReader(root, opts, b)
+		d := newDraft()
+		d.lane(r.serviceLane())
+		r.walkUseCase(d, "session/whoami", 0)
+		if len(d.steps) != 1 {
+			t.Fatalf("nodes = %q", dump(d.steps))
+		}
+		return d.steps[0].(*catalog.Step), r.consumes(), b
+	}
+
+	step, calls, b := read(flowOptions{context: "edge", svcID: "edge.gateway", service: "gateway"})
+	if step.Kind != catalog.StepRPC || step.To != "partner-booking" || step.Ref != "partner-booking-api.v1/getUser" || step.Status != catalog.StatusDeclared {
+		t.Errorf("rpc step = %+v", step)
+	}
+	if len(calls) != 1 || calls[0].Peer != "partner-booking" || calls[0].Status != catalog.StatusDeclared {
+		t.Errorf("consumes = %+v", calls)
+	}
+	var said bool
+	for _, warning := range b.Warnings {
+		said = said || strings.Contains(warning.Message, "read as calling partner-booking")
+	}
+	if !said {
+		t.Errorf("nothing said about the reading; warnings = %+v", b.Warnings)
+	}
+
+	step, calls, _ = read(flowOptions{context: "edge", svcID: "edge.gateway", service: "gateway", externals: map[string]string{"partner-booking-api.v1": "partner"}})
+	if step.To != "partner" || calls[0].Peer != "partner" {
+		t.Errorf("with externals: step to %q, consumes %+v", step.To, calls)
+	}
+
+	step, calls, _ = read(flowOptions{context: "edge", svcID: "edge.gateway", service: "gateway", peers: map[string]string{"partner-booking-api.v1": "shop.partner"}})
+	if step.To != "shop.partner" || calls[0].Peer != "shop.partner" {
+		t.Errorf("with peers: step to %q, consumes %+v", step.To, calls)
+	}
+}

package/plugins/extract-go/ids.go

@@ -0,0 +1,92 @@
+package main
+
+import "strings"
+
+// The id rules, in one place. Everything downstream - a table saying which
+// aggregate it persists, a flow step naming an event, a link on a page - is a
+// string built by one of these, so they are worth having exactly once.
+
+func serviceID(context, service string) string { return context + "." + service }
+
+func aggregateID(service, aggregate string) string { return service + "." + aggregate }
+
+func blockID(aggregate, block string) string { return aggregate + "." + block }
+
+func eventID(aggregate, name string) string { return aggregate + "." + name }
+
+// slug turns a Go identifier into the kebab-case form ids and urls use:
+// PriceList becomes price-list, Address becomes address, ID stays id.
+func slug(name string) string {
+	var b strings.Builder
+
+	runes := []rune(name)
+	for i, r := range runes {
+		upper := r >= 'A' && r <= 'Z'
+		if upper && i > 0 {
+			// A dash goes in at the start of a word, which is either a lower
+			// letter followed by an upper one (orderLine) or the end of an
+			// acronym followed by a word (HTTPServer).
+			prevLower := runes[i-1] >= 'a' && runes[i-1] <= 'z'
+			nextLower := i+1 < len(runes) && runes[i+1] >= 'a' && runes[i+1] <= 'z'
+			if prevLower || nextLower {
+				b.WriteRune('-')
+			}
+		}
+		if upper {
+			r = r - 'A' + 'a'
+		}
+		if r == '_' || r == '.' {
+			r = '-'
+		}
+		b.WriteRune(r)
+	}
+
+	// A separator in the source and a word boundary at the same spot would
+	// otherwise give email.Address the slug "email--address".
+	return collapseDashes(b.String())
+}
+
+func collapseDashes(s string) string {
+	for strings.Contains(s, "--") {
+		s = strings.ReplaceAll(s, "--", "-")
+	}
+
+	return strings.Trim(s, "-")
+}
+
+// camel turns a directory name into the operation id a reader expects:
+// change_password becomes ChangePassword.
+func camel(name string) string {
+	var b strings.Builder
+	for _, word := range strings.FieldsFunc(name, func(r rune) bool { return r == '_' || r == '-' }) {
+		runes := []rune(word)
+		if runes[0] >= 'a' && runes[0] <= 'z' {
+			runes[0] = runes[0] - 'a' + 'A'
+		}
+		b.WriteString(string(runes))
+	}
+
+	return b.String()
+}
+
+// title is the human name for a package: user becomes User, price_list becomes
+// Price List.
+// pascal is the name a struct would have for this package: price_list holds
+// PriceList. `title` puts the words apart for a page to read; a type name has
+// them joined.
+func pascal(name string) string {
+	return strings.ReplaceAll(title(name), " ", "")
+}
+
+func title(name string) string {
+	words := strings.FieldsFunc(name, func(r rune) bool { return r == '_' || r == '-' })
+	for i, word := range words {
+		runes := []rune(word)
+		if runes[0] >= 'a' && runes[0] <= 'z' {
+			runes[0] = runes[0] - 'a' + 'A'
+		}
+		words[i] = string(runes)
+	}
+
+	return strings.Join(words, " ")
+}