@shortlink-org/portolan 0.1.0

package/plugins/extract-asyncapi/extract.go

@@ -0,0 +1,315 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+	"gopkg.in/yaml.v3"
+)
+
+func extract(in plugin.Input, opts Options) (plugin.Response, error) {
+	b := &plugin.Builder{}
+	root := in.Root
+
+	if opts.Context == "" {
+		opts.Context = filepath.Base(root)
+	}
+	if opts.Service == "" {
+		opts.Service = filepath.Base(root)
+	}
+
+	specPath, err := findSpec(root, opts.Spec, b)
+	if err != nil {
+		return plugin.Response{}, err
+	}
+
+	doc, err := load(specPath)
+	if err != nil {
+		return plugin.Response{}, fmt.Errorf("%s: %w", specPath, err)
+	}
+
+	source := filepath.ToSlash(specPath)
+	service := opts.Context + "." + opts.Service
+
+	channels := readChannels(doc, source, service, b)
+	if len(channels) == 0 {
+		b.Warn(service, source+" declares no channels")
+	}
+
+	fragment := catalog.Catalog{
+		GeneratedAt: in.GeneratedAt,
+		Commit:      in.Commit,
+		Contexts: []catalog.BoundedContext{{
+			ID:   opts.Context,
+			Slug: opts.Context,
+			// Named by whichever source knows the name, as the OpenAPI
+			// extractor's fragment says beside the same gap: this document
+			// describes what the service says on the bus, not what it is
+			// called.
+			Services: []catalog.Service{{
+				ID:         service,
+				Slug:       opts.Service,
+				Provides:   []catalog.RpcService{},
+				Consumes:   []catalog.RpcCall{},
+				Aggregates: []catalog.Aggregate{},
+				Channels:   channels,
+			}},
+		}},
+		Defs:  map[string]catalog.TypeDef{},
+		Flows: []catalog.Flow{},
+		Adrs:  []catalog.Adr{},
+	}
+
+	encoded, err := json.MarshalIndent(fragment, "", "  ")
+	if err != nil {
+		return plugin.Response{}, err
+	}
+
+	b.File(firstNonEmpty(opts.Out, "bus.json"), string(encoded)+"\n")
+
+	return b.Response(), nil
+}
+
+// draft is a channel while it is being read: the messages arrive from the
+// operations that name them, one direction at a time, and the same message may
+// be named twice.
+type draft struct {
+	channel catalog.Channel
+	seen    map[string]bool
+}
+
+func (d *draft) add(message catalog.ChannelMessage) {
+	if message.Name == "" {
+		return
+	}
+	key := string(message.Direction) + " " + message.Name
+	if d.seen[key] {
+		return
+	}
+	d.seen[key] = true
+	d.channel.Messages = append(d.channel.Messages, message)
+}
+
+func readChannels(doc *document, source, service string, b *plugin.Builder) []catalog.Channel {
+	if doc.major == 2 {
+		return channelsV2(doc, source, service, b)
+	}
+
+	return channelsV3(doc, source, service, b)
+}
+
+// channelsV3 reads 3.x: channels declare addresses and messages, and operations
+// say which way each message travels.
+func channelsV3(doc *document, source, service string, b *plugin.Builder) []catalog.Channel {
+	drafts := map[string]*draft{}
+	var order []string
+
+	for _, c := range entries(child(doc.root, "channels")) {
+		address := firstNonEmpty(text(child(c.value, "address")), c.key)
+		drafts[c.key] = &draft{
+			channel: catalog.Channel{
+				Address:  address,
+				Title:    text(child(c.value, "title")),
+				Doc:      text(child(c.value, "description")),
+				Messages: []catalog.ChannelMessage{},
+				Source:   source,
+			},
+			seen: map[string]bool{},
+		}
+		order = append(order, c.key)
+	}
+
+	for _, op := range entries(child(doc.root, "operations")) {
+		direction, ok := directionOf(text(child(op.value, "action")))
+		if !ok {
+			b.Warn(service, source+": operation "+op.key+" has no action, so nothing says which way its messages travel")
+
+			continue
+		}
+
+		_, ref := doc.deref(child(op.value, "channel"))
+		key := refKey(ref)
+		d, found := drafts[key]
+		if !found {
+			b.Warn(service, source+": operation "+op.key+" names channel "+key+", which the document does not declare")
+
+			continue
+		}
+
+		named := items(child(op.value, "messages"))
+		if len(named) == 0 {
+			// An operation that names no message carries everything the
+			// channel declares, which is how a document says "this whole
+			// channel goes this way".
+			for _, m := range entries(child(channelNode(doc, key), "messages")) {
+				d.add(doc.message(m.value, m.key, direction))
+			}
+
+			continue
+		}
+
+		for _, message := range named {
+			node, ref := doc.deref(message)
+			if node == nil {
+				b.Warn(service, source+": operation "+op.key+" names message "+ref+", which is not in this document")
+
+				continue
+			}
+			d.add(doc.message(node, refKey(ref), direction))
+		}
+	}
+
+	out := make([]catalog.Channel, 0, len(order))
+	for _, key := range order {
+		d := drafts[key]
+		if len(d.channel.Messages) == 0 {
+			b.Warn(service, source+": channel "+d.channel.Address+" has no operation, so nothing says which way it travels")
+		}
+		out = append(out, d.channel)
+	}
+
+	return out
+}
+
+// channelsV2 reads 2.x, where the channel key is the address and the two
+// operations are named from the client's side: `subscribe` is what the
+// application produces, `publish` is what it consumes.
+func channelsV2(doc *document, source, service string, b *plugin.Builder) []catalog.Channel {
+	var out []catalog.Channel
+
+	for _, c := range entries(child(doc.root, "channels")) {
+		d := &draft{
+			channel: catalog.Channel{
+				Address:  c.key,
+				Doc:      text(child(c.value, "description")),
+				Messages: []catalog.ChannelMessage{},
+				Source:   source,
+			},
+			seen: map[string]bool{},
+		}
+
+		for _, op := range []struct {
+			key       string
+			direction catalog.ChannelDirection
+		}{
+			{"subscribe", catalog.ChannelSend},
+			{"publish", catalog.ChannelReceive},
+		} {
+			node := child(c.value, op.key)
+			if node == nil {
+				continue
+			}
+
+			message := child(node, "message")
+			candidates := items(child(message, "oneOf"))
+			if len(candidates) == 0 && message != nil {
+				candidates = []*yaml.Node{message}
+			}
+
+			for _, candidate := range candidates {
+				resolved, ref := doc.deref(candidate)
+				if resolved == nil {
+					b.Warn(service, source+": channel "+c.key+" names message "+ref+", which is not in this document")
+
+					continue
+				}
+				d.add(doc.message(resolved, refKey(ref), op.direction))
+			}
+		}
+
+		if len(d.channel.Messages) == 0 {
+			b.Warn(service, source+": channel "+c.key+" declares no message")
+		}
+
+		out = append(out, d.channel)
+	}
+
+	return out
+}
+
+// message reads one message object into the fact the catalog keeps: the name it
+// goes by on the wire, and enough prose to read it without opening the
+// document.
+//
+// The name is the message's own `name` when it has one, and the key it is filed
+// under when it does not. Those are different things - the key is the
+// document's, the name is the bus's - and an event's wire name is compared
+// against this, so a document that leaves `name` out is saying the two are the
+// same.
+func (d *document) message(node *yaml.Node, key string, direction catalog.ChannelDirection) catalog.ChannelMessage {
+	resolved, _ := d.deref(node)
+	if resolved == nil {
+		resolved = node
+	}
+
+	return catalog.ChannelMessage{
+		Name:      firstNonEmpty(text(child(resolved, "name")), key),
+		Title:     text(child(resolved, "title")),
+		Doc:       firstNonEmpty(text(child(resolved, "summary")), text(child(resolved, "description"))),
+		Direction: direction,
+	}
+}
+
+func channelNode(doc *document, key string) *yaml.Node {
+	return child(doc.root, "channels", key)
+}
+
+func directionOf(action string) (catalog.ChannelDirection, bool) {
+	switch action {
+	case "send":
+		return catalog.ChannelSend, true
+	case "receive":
+		return catalog.ChannelReceive, true
+	}
+
+	return "", false
+}
+
+// findSpec locates the document. Told where it is, it looks there; otherwise it
+// searches, and says what it found so a service with two documents does not get
+// described from whichever one sorted first without anybody noticing.
+func findSpec(root, declared string, b *plugin.Builder) (string, error) {
+	if declared != "" {
+		return filepath.Join(root, filepath.FromSlash(declared)), nil
+	}
+
+	var found []string
+	err := filepath.WalkDir(root, func(p string, entry os.DirEntry, err error) error {
+		if err != nil || entry.IsDir() {
+			return err
+		}
+		switch entry.Name() {
+		case "asyncapi.yaml", "asyncapi.yml":
+			found = append(found, p)
+		}
+
+		return nil
+	})
+	if err != nil {
+		return "", err
+	}
+
+	if len(found) == 0 {
+		return "", fmt.Errorf("no asyncapi document under %s, and none named in the options", root)
+	}
+	if len(found) > 1 {
+		b.Warn("", "found "+strings.Join(found, ", ")+"; reading the first and ignoring the rest")
+	}
+
+	return found[0], nil
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			return value
+		}
+	}
+
+	return ""
+}

package/plugins/extract-asyncapi/extract_test.go

@@ -0,0 +1,197 @@
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func run3(t *testing.T, root string, opts Options) plugin.Response {
+	t.Helper()
+
+	resp, err := extract(
+		plugin.Input{Root: root, Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"},
+		opts,
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(resp.Files) != 1 {
+		t.Fatalf("expected one fragment, got %d files", len(resp.Files))
+	}
+
+	return resp
+}
+
+func channelsOf(t *testing.T, resp plugin.Response) []catalog.Channel {
+	t.Helper()
+
+	var out catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
+		t.Fatal(err)
+	}
+
+	return out.Contexts[0].Services[0].Channels
+}
+
+func byAddress(channels []catalog.Channel, address string) *catalog.Channel {
+	for i := range channels {
+		if channels[i].Address == address {
+			return &channels[i]
+		}
+	}
+
+	return nil
+}
+
+func spell(messages []catalog.ChannelMessage) []string {
+	out := make([]string, 0, len(messages))
+	for _, m := range messages {
+		out = append(out, string(m.Direction)+" "+m.Name)
+	}
+
+	return out
+}
+
+// An operation that names no message carries everything the channel declares,
+// which is how a document says "this whole channel goes one way".
+func TestSendTakesTheWholeChannel(t *testing.T) {
+	channels := channelsOf(t, run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"}))
+
+	basket := byAddress(channels, "shop.cart.basket")
+	if basket == nil {
+		t.Fatalf("no basket channel in %v", channels)
+	}
+
+	want := "send cart.BasketCreated,send cart.BasketCheckedOut"
+	if got := strings.Join(spell(basket.Messages), ","); got != want {
+		t.Errorf("messages = %s, want %s", got, want)
+	}
+}
+
+// The address is the channel's own when it names one, not the key it is filed
+// under: the key is the document's word, the address is the broker's, and an
+// event's wire is compared against the second.
+func TestAddressBeatsTheKey(t *testing.T) {
+	channels := channelsOf(t, run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"}))
+
+	if byAddress(channels, "basket") != nil {
+		t.Error("the channel key was taken for an address")
+	}
+}
+
+// What the service listens for is the half no publisher's source could say.
+func TestReceiveIsReadFromTheOperation(t *testing.T) {
+	channels := channelsOf(t, run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"}))
+
+	sessions := byAddress(channels, "auth_session")
+	if sessions == nil {
+		t.Fatalf("no session channel in %v", channels)
+	}
+
+	if got := strings.Join(spell(sessions.Messages), ","); got != "receive auth.SessionEnded" {
+		t.Errorf("messages = %s", got)
+	}
+}
+
+// The name on the wire and the prose beside it, so a reader does not have to
+// open the document to know what arrived.
+func TestMessageCarriesItsNameAndSummary(t *testing.T) {
+	channels := channelsOf(t, run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"}))
+
+	basket := byAddress(channels, "shop.cart.basket")
+	created := basket.Messages[0]
+
+	if created.Name != "cart.BasketCreated" {
+		t.Errorf("name = %q", created.Name)
+	}
+	if created.Title != "Basket created" {
+		t.Errorf("title = %q", created.Title)
+	}
+	if created.Doc != "A shopper has a basket." {
+		t.Errorf("doc = %q", created.Doc)
+	}
+}
+
+// A channel nothing operates on is still a channel - the address is a fact -
+// but which way it travels is not known, and silence about that is what the
+// diagnostic is for.
+func TestChannelWithNoOperationIsReportedNotDropped(t *testing.T) {
+	resp := run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"})
+
+	telemetry := byAddress(channelsOf(t, resp), "shop.cart.telemetry")
+	if telemetry == nil {
+		t.Fatal("a channel with no operation was dropped")
+	}
+	if len(telemetry.Messages) != 0 {
+		t.Errorf("messages = %v", telemetry.Messages)
+	}
+
+	var said bool
+	for _, d := range resp.Warnings() {
+		if strings.Contains(d.Message, "shop.cart.telemetry") {
+			said = true
+		}
+	}
+	if !said {
+		t.Errorf("nothing was said about it: %v", resp.Warnings())
+	}
+}
+
+// 2.x names its operations from the client's side: `subscribe` is what the
+// application produces and `publish` is what it consumes. Reading them the
+// obvious way gets every arrow backwards.
+func TestVersionTwoOperationsAreReadFromTheApplicationsSide(t *testing.T) {
+	channels := channelsOf(t, run3(t, "testdata/v2", Options{Context: "shop", Service: "billing"}))
+
+	raised := byAddress(channels, "billing_invoice")
+	if raised == nil {
+		t.Fatalf("no invoice channel in %v", channels)
+	}
+	want := "send billing.InvoiceRaised,send billing.InvoiceSettled"
+	if got := strings.Join(spell(raised.Messages), ","); got != want {
+		t.Errorf("subscribe means the application sends; got %s", got)
+	}
+
+	consumed := byAddress(channels, "auth_user")
+	if consumed == nil {
+		t.Fatalf("no auth_user channel in %v", channels)
+	}
+	if got := strings.Join(spell(consumed.Messages), ","); got != "receive auth.UserRegistered" {
+		t.Errorf("publish means the application receives; got %s", got)
+	}
+}
+
+// The fragment describes what the service says on the bus and nothing else.
+func TestFragmentClaimsNothingItDoesNotKnow(t *testing.T) {
+	var out catalog.Catalog
+	resp := run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"})
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
+		t.Fatal(err)
+	}
+
+	service := out.Contexts[0].Services[0]
+	if service.Name != "" || service.Readme != "" || service.Repo != "" {
+		t.Errorf("the bus fragment should not name the service: %+v", service)
+	}
+	if len(service.Aggregates) != 0 || len(service.Provides) != 0 {
+		t.Error("the bus fragment should carry no aggregates and no interfaces")
+	}
+}
+
+// The fragment's name is the manifest's to choose, and `bus.json` when it does
+// not.
+func TestFragmentName(t *testing.T) {
+	resp := run3(t, "testdata/v3", Options{Context: "shop", Service: "cart"})
+	if resp.Files[0].Name != "bus.json" {
+		t.Errorf("name = %q", resp.Files[0].Name)
+	}
+
+	resp = run3(t, "testdata/v3", Options{Context: "shop", Service: "cart", Out: "channels.json"})
+	if resp.Files[0].Name != "channels.json" {
+		t.Errorf("name = %q", resp.Files[0].Name)
+	}
+}

package/plugins/extract-asyncapi/main.go

@@ -0,0 +1,48 @@
+// Package main is portolan-extract-asyncapi: an AsyncAPI document in, a catalog
+// fragment out.
+//
+// It describes one aspect of a service - what it puts on the bus and what it
+// listens for - and nothing else. The events themselves come from a different
+// extractor reading the domain, and the two meet in the merge: that one says an
+// aggregate raises BasketCreated and calls it `cart.BasketCreated` on the wire,
+// this one says the service declares a channel carrying that name. Neither
+// knows the other exists, and the pages hold the two against each other.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// Options are what the manifest tells the extractor: the things an AsyncAPI
+// document does not say about the estate it belongs to.
+type Options struct {
+	Context string `json:"context"`
+	Service string `json:"service"`
+
+	// Spec is the document, relative to the input root. Left out, the
+	// extractor looks for one.
+	Spec string `json:"spec,omitempty"`
+
+	Out string `json:"out,omitempty"`
+}
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-extract-asyncapi:", err)
+		os.Exit(1)
+	}
+}
+
+func run(stdin io.Reader, stdout io.Writer) error {
+	return plugin.Serve(stdin, stdout, descriptor(), func(req plugin.Request, opts Options) (plugin.Response, error) {
+		if req.Input.Root == "" {
+			return plugin.Response{}, fmt.Errorf("no input root: an extractor has nothing to read")
+		}
+
+		return extract(req.Input, opts)
+	})
+}

package/plugins/extract-asyncapi/options.schema.json

@@ -0,0 +1,26 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context that owns the service this document belongs to. Defaults to the name of the input directory.",
+      "examples": ["shop"]
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the service the document describes. Defaults to the name of the input directory.",
+      "examples": ["cart"]
+    },
+    "spec": {
+      "type": "string",
+      "description": "The AsyncAPI document, relative to the input root. Left out, the extractor looks for one.",
+      "examples": ["src/infrastructure/bus/gen/asyncapi.yaml"]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "bus.json"
+    }
+  }
+}