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 ¶
const ( NodeScript = "script" NodeLibrary = "library" NodeAsset = "asset" NodeSource = "source" NodeSchema = "schema" NodeTable = "table" NodeChannel = "channel" NodeOutput = "output" NodeEnd = "endpoint" )
The kinds of node.
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.
const ( GroupApplication = "application" GroupSchema = "schema" GroupOutside = "outside" )
The groups a node is drawn in.
const ( FindingLibraryVersion = "library_version" FindingUnwrittenTable = "unwritten_table" FindingForeignSchema = "foreign_schema" )
The kinds of finding.
const ( ChangeAdded = "added" ChangeRemoved = "removed" ChangeChanged = "changed" ChangeUnchanged = "unchanged" )
The marks a compared diagram carries.
Variables ¶
This section is empty.
Functions ¶
Types ¶
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.
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 ¶
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)
// Schedules, Bindings and EventSources are a script's handlers (#2441):
// its schedules, its endpoints and the webhook sources it runs for.
Schedules(ctx context.Context, scriptID string) ([]script.Schedule, error)
Bindings(ctx context.Context, scriptID string) ([]Binding, error)
EventSources(ctx context.Context, scriptID string) []string
// 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.