@shortlink-org/portolan 0.1.0 → 0.2.1

package/plugins/extract-go/httpclient.go

@@ -1,174 +0,0 @@
-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

@@ -1,296 +0,0 @@
-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

@@ -1,92 +0,0 @@
-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, " ")
-}