appdiagram

package
v1.157.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package appdiagram derives how an application's parts fit together (#2540): which webhook source starts which script, which script reads and writes which table, loads which library, writes which asset or notifies which channel, which asset calls which endpoint or embeds which form, and what the parts reach outside the application. It is derived the way a script's Flow diagram is, from the parts' sources and stored settings at one version of the application, never from a run, so it needs no run to exist and cannot disagree with the code. A name a source computes when it runs is drawn as computed, never matched to a part by a guess.

It also names what it finds wrong: a script loading one of the application's libraries at a version other than the one the version of the application pins, a table of the application's schema its scripts read and no part writes, and a script using a schema the application does not hold.

Index

Constants

View Source
const (
	NodeScript  = "script"
	NodeLibrary = "library"
	NodeAsset   = "asset"
	NodeSource  = "source"
	NodeSchema  = "schema"
	NodeTable   = "table"
	NodeChannel = "channel"
	NodeOutput  = "output"
	NodeEnd     = "endpoint"
)

The kinds of node.

View Source
const (
	LinkEvent    = "event"
	LinkReads    = "reads"
	LinkWrites   = "writes"
	LinkLoads    = "loads"
	LinkExports  = "exports"
	LinkRefresh  = "refreshes"
	LinkNotifies = "notifies"
	LinkPosts    = "posts"
	LinkCalls    = "calls"
	LinkEmbeds   = "embeds"
	LinkSubmits  = "submits"
)

The kinds of link.

View Source
const (
	GroupApplication = "application"
	GroupSchema      = "schema"
	GroupOutside     = "outside"
)

The groups a node is drawn in.

View Source
const (
	FindingLibraryVersion = "library_version"
	FindingUnwrittenTable = "unwritten_table"
	FindingForeignSchema  = "foreign_schema"
)

The kinds of finding.

View Source
const (
	ChangeAdded     = "added"
	ChangeRemoved   = "removed"
	ChangeChanged   = "changed"
	ChangeUnchanged = "unchanged"
)

The marks a compared diagram carries.

Variables

This section is empty.

Functions

func Problems

func Problems(d *Diagram) []string

Problems is the findings as the lines manage_application get reports.

Types

type Binding

type Binding struct {
	Name string
	Path string
}

Binding is a script's endpoint binding as the diagram reads it.

type Diagram

type Diagram struct {
	// Version is what was drawn: "current", "latest" or a release number.
	Version      string    `json:"version"`
	ComparedWith string    `json:"compared_with,omitempty"`
	Nodes        []Node    `json:"nodes"`
	Links        []Link    `json:"links"`
	Groups       []Group   `json:"groups"`
	Findings     []Finding `json:"findings"`
}

Diagram is one version of an application drawn.

func Build

func Build(ctx context.Context, r Reader, in Input) *Diagram

Build draws in.

func Compare

func Compare(next, prev *Diagram) *Diagram

Compare marks next against prev: each node and link added, removed (carried over from prev) or unchanged, a part whose version moved changed, and a link whose detail moved (a load's version) changed.

type Finding

type Finding struct {
	Kind string `json:"kind" example:"library_version"`
	// Node is the node it is about.
	Node    string `json:"node"`
	Message string `json:"message"`
	// Blocks is true for a finding a release refuses.
	Blocks bool `json:"blocks"`
}

Finding is one thing the diagram finds wrong.

type Group

type Group struct {
	ID     string `json:"id"`
	Label  string `json:"label"`
	Parent string `json:"parent,omitempty"`
}

Group is a box the nodes are drawn in.

type Input

type Input struct {
	App     *application.Application
	Parts   []Part
	Version string
}

Input is what a diagram is drawn from.

type Link struct {
	From string `json:"from"`
	To   string `json:"to"`
	Kind string `json:"kind" example:"reads"`
	// Detail is the version a load names, the endpoint an asset calls.
	Detail string `json:"detail,omitempty"`
	// Change and WasDetail mark a compared diagram's link: a link whose
	// detail moved (a load's version) is changed, with what it said.
	Change    string `json:"change,omitempty"`
	WasDetail string `json:"was_detail,omitempty"`
}

Link is one way a part reaches another, or something outside: always from the part that acts (a script reads and writes a table, an asset calls an endpoint, a source starts a script).

type Node

type Node struct {
	ID    string `json:"id" example:"script:5b0c..."`
	Kind  string `json:"kind" example:"script"`
	Label string `json:"label" example:"Nightly order sync"`
	Group string `json:"group" example:"application"`
	// Part is true for a part of the application, PartID its id.
	Part   bool   `json:"part"`
	PartID string `json:"part_id,omitempty"`
	// Version is the part's version this diagram is drawn at, 0 for none.
	Version int `json:"version,omitempty"`
	// Computed is true for a name the source computes when it runs.
	Computed bool `json:"computed"`
	// Detail is what the node's card adds: a script's schedule and its
	// endpoint, a table's connection.
	Detail []string `json:"detail"`
	// Change and WasVersion mark a compared diagram's node.
	Change     string `json:"change,omitempty"`
	WasVersion int    `json:"was_version,omitempty"`
}

Node is a part, or what a part reaches.

type Part

type Part struct {
	application.Part
	// Version is the version drawn, 0 for a webhook source or the schema.
	Version int
}

Part is one part as the diagram reads it at the version drawn.

type Reader

type Reader interface {
	Script(ctx context.Context, id string) (*script.Script, error)
	ScriptVersion(ctx context.Context, id string, version int) (*script.Version, error)
	Schedule(ctx context.Context, scriptID string) (*script.Schedule, error)
	Binding(ctx context.Context, scriptID string) (*Binding, error)
	// AssetName is an asset's name and the output identity a script writes
	// it under; ok false for an asset the caller cannot open.
	Asset(ctx context.Context, id string) (name, identity string, ok bool)
	// AssetContent is an asset version's content, empty for one not text.
	AssetContent(ctx context.Context, id string, version int) string
	// SchemaWrites is the tables the schema's migrations write rows to.
	SchemaWrites(ctx context.Context, connection, schema string) []string
	// IsAppDB reports whether a connection is an application database.
	IsAppDB(connection string) bool
}

Reader reads what the diagram is derived from.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL