archsight 0.4.0 → 0.4.1

data/lib/archsight/openapi.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require_relative "resources"
+
+module Archsight
+  # The OpenAPI document of the REST API: the hand-written base (`web/api/openapi/spec.yaml`: the fixed endpoints such
+  # as pages, assets, search and the editor, with their prose, examples and error shapes) plus what the model knows and
+  # nobody should type twice: one schema per kind with its annotations (type, enum, description, default), its `spec`
+  # relations and its relations, the list of kinds, and the instance detail schema that is one of them. A new kind, a
+  # changed enum or another relation shows up in the documentation without touching the YAML.
+  #
+  #   Archsight::OpenAPI.document # => Hash, `.to_yaml` is what GET /api/v1/openapi.yaml serves
+  module OpenAPI
+    BASE = File.join(__dir__, "web", "api", "openapi", "spec.yaml")
+
+    # The operations that answer with the detail of one instance, whose kind the path names
+    DETAIL_PATHS = ["/api/v1/kinds/{kind}/instances/{name}", "/kinds/{kind}/instances/{name}.json"].freeze
+
+    # What an annotation of a type is in the JSON. The value is the one of the YAML file, so a number may also be its
+    # string ("100"); only a computed annotation is always a number. Everything else is a string.
+    TYPES = {
+      Integer => { "type" => %w[integer string] },
+      Float => { "type" => %w[number string] }
+    }.freeze
+
+    NAMES = { "type" => "array", "items" => { "type" => "string" } }.freeze
+
+    class << self
+      # @return [Hash] the complete document; built once, the model does not change while the server runs
+      def document
+        @document ||= build
+      end
+
+      # Forget the built document (the model was changed, in a test)
+      def reset!
+        @document = nil
+      end
+
+      # The name of the schema of a kind
+      def schema_name(kind) = "#{kind}Instance"
+
+      # The schema of one kind: the detail of an instance as GET /api/v1/kinds/{kind}/instances/{name} returns it
+      # @param kind [String] name of a kind
+      # @return [Hash]
+      def kind_schema(kind)
+        klass = Archsight::Resources[kind]
+        schema = {
+          "type" => "object",
+          "required" => %w[kind name metadata spec relations references],
+          "x-layer" => klass.layer,
+          "properties" => {
+            "kind" => { "type" => "string", "const" => kind },
+            "name" => { "type" => "string", "description" => "Name of the instance" },
+            "metadata" => { "type" => "object", "properties" => { "annotations" => annotations_schema(klass) } },
+            "annotation_formats" => { "type" => "object", "additionalProperties" => { "type" => "string" },
+                                      "description" => "How the UI shows each annotation that is set (markdown, link, tag_list, ...)" },
+            "annotation_links" => { "type" => "object", "additionalProperties" => true,
+                                    "description" => "Annotations whose value names resources, with the resources they resolve to" },
+            "spec" => spec_schema(klass),
+            "relations" => relations_schema(klass),
+            "references" => references_schema,
+            "diagram" => { "type" => %w[string null], "description" => "The `architecture/diagram` annotation as inline SVG" }
+          }
+        }
+        schema["description"] = klass.description.strip if klass.description
+        schema
+      end
+
+      private
+
+      def build
+        document = YAML.safe_load_file(BASE, permitted_classes: [], aliases: true)
+        kinds = Archsight::Resources.resource_classes.keys.sort
+        schemas = document.fetch("components").fetch("schemas")
+        add_schemas(schemas, kinds)
+        document.dig("components", "parameters", "kind")["schema"] = { "$ref" => "#/components/schemas/KindName" }
+        DETAIL_PATHS.each { |path| use_detail_schema(document.fetch("paths").fetch(path)) }
+        # the schemas share small hashes: a copy of each keeps YAML from writing anchors and aliases for them
+        JSON.parse(JSON.generate(document))
+      end
+
+      def add_schemas(schemas, kinds)
+        kinds.each do |kind|
+          name = schema_name(kind)
+          raise ArgumentError, "OpenAPI: the schema #{name} of #{kind} clashes with a schema of the base spec" if schemas.key?(name)
+
+          schemas[name] = kind_schema(kind)
+        end
+        schemas["KindName"] = {
+          "type" => "string", "enum" => kinds,
+          "description" => "Name of a resource kind. A kind that was renamed is still accepted under its old name."
+        }
+        schemas["InstanceDetail"] = {
+          "description" => "An instance with its relations and references: the schema depends on the kind",
+          "oneOf" => kinds.map { |kind| { "$ref" => "#/components/schemas/#{schema_name(kind)}" } },
+          "discriminator" => { "propertyName" => "kind", "mapping" => kinds.to_h { |kind| [kind, "#/components/schemas/#{schema_name(kind)}"] } }
+        }
+      end
+
+      def use_detail_schema(path_item)
+        path_item.dig("get", "responses", "200", "content", "application/json")["schema"] = { "$ref" => "#/components/schemas/InstanceDetail" }
+      end
+
+      # The annotations of the kind that are set; every annotation is optional. Other annotations are allowed.
+      def annotations_schema(klass)
+        fixed, patterns = klass.annotations.partition { |annotation| !annotation.pattern? }
+        schema = {
+          "type" => "object", "additionalProperties" => true,
+          "properties" => fixed.to_h { |annotation| [annotation.key, annotation_schema(annotation)] }
+        }
+        schema["patternProperties"] = patterns.to_h { |annotation| [pattern_of(annotation.key), annotation_schema(annotation)] } unless patterns.empty?
+        schema
+      end
+
+      def annotation_schema(annotation)
+        schema = (TYPES[annotation.type] || { "type" => "string" }).dup
+        description = annotation.description.to_s.strip
+        description = "#{description}\n\nRendered to HTML in the response." if annotation.format == :markdown && !description.empty?
+        schema["description"] = description unless description.empty?
+        if annotation.enum && annotation.list?
+          # a list is one string of comma separated values, each of them one of the enum
+          schema["description"] = "#{description}\n\nComma separated list of: #{annotation.enum.join(", ")}.".strip
+          schema["x-items-enum"] = annotation.enum
+        elsif annotation.enum
+          schema["enum"] = annotation.enum
+        end
+        schema["default"] = annotation.default unless annotation.default.nil?
+        schema["deprecated"] = true if annotation.deprecated
+        schema
+      end
+
+      # `link/*` -> a regular expression for the keys it matches
+      def pattern_of(key) = "^#{Regexp.escape(key).gsub('\*', ".+")}$"
+
+      # What the file says: spec.<verb>.<key>: [names]
+      def spec_schema(klass)
+        properties = {}
+        klass.declared_relations.each do |verb, key, target|
+          verb_schema = (properties[verb.to_s] ||= { "type" => "object", "properties" => {} })
+          verb_schema["properties"][key.to_s] = NAMES.merge("description" => "Names of #{target} resources")
+        end
+        { "type" => "object", "additionalProperties" => true, "properties" => properties,
+          "description" => "The relations as written in the resource: verb, then the kind's collection, then the names" }
+      end
+
+      # The outgoing relations that exist: verb, then the kind of the target, then the names
+      def relations_schema(klass)
+        properties = {}
+        klass.relations.each do |verb, _key, target|
+          verb_schema = (properties[verb.to_s] ||= { "type" => "object" })
+          if Archsight::Resources::DERIVED_VERBS.include?(verb)
+            verb_schema["additionalProperties"] = NAMES # targets of any kind, grouped by the kind they are
+          else
+            (verb_schema["properties"] ||= {})[target.to_s] = NAMES
+          end
+        end
+        { "type" => "object", "additionalProperties" => false, "properties" => properties,
+          "description" => "Outgoing relations that have targets, grouped by verb and the kind of the target" }
+      end
+
+      def references_schema
+        { "type" => "object", "additionalProperties" => { "type" => "object", "additionalProperties" => NAMES },
+          "description" => "Incoming relations grouped by the kind of the source and the verb" }
+      end
+    end
+  end
+end

data/lib/archsight/page_tree.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "kramdown"
-require "kramdown-parser-gfm"
+require_relative "markdown"
 
 module Archsight
   # PageTree builds the sidebar tree, breadcrumbs and tables of contents for Page resources
@@ -63,7 +62,7 @@ module Archsight
 
     # Flat table of contents [{level:, id:, text:}] of a markdown body
     def self.toc(markdown)
-      doc = Kramdown::Document.new(markdown.to_s, input: "GFM")
+      doc = Archsight::Markdown.document(markdown)
       entries = [] #: Array[Hash[String, untyped]]
       collect_toc(doc.to_toc, entries)
       entries

data/lib/archsight/resources/application_interface.rb

@@ -25,6 +25,17 @@ class Archsight::Resources::ApplicationInterface < Archsight::Resources::Base
     - gRPC services
     - Message queues (producer/consumer interfaces)
     - WebSocket endpoints
+
+    ## Reachability
+
+    An interface is `servedBy` the `TechnologyInterface` that carries it (a protocol, an authentication method) and
+    by the `TechnologyCommunicationNetwork`s on which it can be reached, just as a `TechnologyNode` attaches to the
+    networks it is on. Together with `api/authenticationMethod` this decides the exposure of the interface: an
+    interface without authentication on an internal network is a different risk than on a network that
+    internet-facing components attach to. The network page lists the interfaces as incoming "served by".
+
+    Write the networks only when they are known. An interface without a network makes no claim about where it can
+    be reached.
   MD
 
   icon "usb"
@@ -47,6 +58,7 @@ class Archsight::Resources::ApplicationInterface < Archsight::Resources::Base
              enum: ["none", "hard coded", "pbac", "abac", "rbac"]
 
   relation :servedBy, :technologyComponents, :TechnologyInterface
+  relation :servedBy, :technologyCommunicationNetworks, :TechnologyCommunicationNetwork
   relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :serves, :dataObjects, :DataObject
 end

data/lib/archsight/resources/technology_communication_network.rb

@@ -50,6 +50,8 @@ class Archsight::Resources::TechnologyCommunicationNetwork < Archsight::Resource
     - An overlay that software builds is `realizedBy` that `ApplicationComponent` or `ApplicationService` (an SDN agent,
       a network operator, a load-balancer controller), also when the software runs on the nodes the network serves
     - A `TechnologyNode` is `servedBy` the networks it is attached to; the network page lists them
+    - An `ApplicationInterface` is `servedBy` the networks on which it can be reached (only when that is known); the
+      network page lists the interfaces, which shows what a network exposes
     - A network is `realizedBy` the `TechnologyDevice`s that build it (its switches and routers) and `connects` the
       devices attached to it (servers, firewalls, appliances). Both are written on the network, so a switch that is
       also attached to the network it builds closes no cycle

data/lib/archsight/version.rb

@@ -4,5 +4,5 @@
 # Do not edit manually.
 
 module Archsight
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

data/lib/archsight/web/api/docs.rb

@@ -11,8 +11,9 @@ module Archsight::Web::API; end
 module Archsight::Web::API::Docs
   extend Sinatra::Extension
 
+  # A page of its own, not the single page app: ReDoc must not get the app's CSS (Pico restyles every <code>)
   get "/docs/api" do
-    serve_vue
+    send_file File.join(settings.public_folder, "vendor", "redoc", "api.html"), type: :html
   end
 
   # GET /api/v1/docs/resources/:filename — auto-generated resource docs

data/lib/archsight/web/api/openapi/spec.yaml

@@ -623,12 +623,10 @@ paths:
                 type: object
                 properties:
                   html:
-                    type: string
-                    nullable: true
+                    type: [string, "null"]
                     description: '`<figure class="asd-diagram">` with the SVG'
                   error:
-                    type: string
-                    nullable: true
+                    type: [string, "null"]
         '400':
           description: Body is not JSON with a `source` string
           content:
@@ -708,9 +706,11 @@ paths:
       summary: Requirements of a selection of resources
       description: |
         The requirements that the resources selected by `of` realize (`implemented`), partially realize
-        (`partial`) or plan (`planned`), merged over all of them: one entry per requirement with the best status and
-        the resources it comes from (`by`). Sorted by priority (must, should, may, none), then name. `story` is
-        rendered HTML.
+        (`partial`) or plan (`planned`), merged over all of them: one entry per requirement, with the best status
+        any of the resources gives it and the resources it comes from (`by`, each with its own status). Sorted by
+        priority (must, should, may, requirements without a priority last), then name. `story` is rendered HTML.
+        `priority` and `status` filter the merged entries, so `status=partial` lists requirements whose best
+        status is partial.
       operationId: getRequirements
       tags:
         - Search
@@ -725,14 +725,14 @@ paths:
         - name: priority
           in: query
           required: false
-          description: Comma separated list, only requirements with one of these priorities
+          description: Comma separated list, only requirements with one of these priorities (must, should, may)
           schema:
             type: string
           example: must,should
         - name: status
           in: query
           required: false
-          description: Comma separated list, only requirements with one of these statuses
+          description: Comma separated list, only requirements with one of these statuses (implemented, partial, planned)
           schema:
             type: string
           example: implemented,partial
@@ -743,33 +743,42 @@ paths:
             application/json:
               schema:
                 type: object
+                required: [query, total, query_time_ms, requirements]
                 properties:
                   query:
                     type: string
+                    description: The `of` query as given
                   total:
                     type: integer
+                    description: Number of requirements returned
                   query_time_ms:
                     type: number
                   requirements:
                     type: array
                     items:
                       type: object
+                      required: [name, status, priority, story, by]
                       properties:
                         name:
                           type: string
+                          description: Name of the MotivationRequirement
                         status:
                           type: string
                           enum: [implemented, partial, planned]
+                          description: The best status among the resources in `by`
                         priority:
-                          type: string
-                          nullable: true
+                          type: [string, "null"]
+                          enum: [must, should, may, null]
+                          description: Priority of the requirement, null if it has none
                         story:
-                          type: string
-                          nullable: true
+                          type: [string, "null"]
+                          description: The requirement's story as rendered HTML, null if it has none
                         by:
                           type: array
+                          description: The selected resources that realize, partially realize or plan the requirement, best status first
                           items:
                             type: object
+                            required: [kind, name, status]
                             properties:
                               kind:
                                 type: string
@@ -778,12 +787,118 @@ paths:
                               status:
                                 type: string
                                 enum: [implemented, partial, planned]
+                                description: The status this resource gives the requirement
+              example:
+                query: 'ApplicationService: name =~ "Backup"'
+                total: 1
+                query_time_ms: 1.4
+                requirements:
+                  - name: "Requirement:Restore"
+                    status: partial
+                    priority: must
+                    story: "<p>As an operator I can restore a backup.</p>"
+                    by:
+                      - kind: ApplicationService
+                        name: Backup
+                        status: partial
         '400':
-          description: Invalid query, or an unknown priority or status
+          description: |
+            `of` is missing or `priority` or `status` holds an unknown value (`BadRequest`), or `of` is not a valid
+            query (`QueryError`, which also returns the query)
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/QueryError'
+                oneOf:
+                  - $ref: '#/components/schemas/Error'
+                  - $ref: '#/components/schemas/QueryError'
+
+  /api/v1/openapi.yaml:
+    get:
+      summary: This OpenAPI document
+      description: |
+        The OpenAPI 3.1 description of this API. The fixed endpoints are written by hand; the schema of every kind
+        (its annotations with type, enum and description, its `spec` and its relations), the list of kinds and the
+        instance detail are generated from the model, so they always describe the kinds this server has.
+      operationId: getOpenApi
+      tags:
+        - Operations
+      responses:
+        '200':
+          description: The OpenAPI document
+          content:
+            text/yaml:
+              schema:
+                type: string
+
+  /maintenance/restart:
+    post:
+      summary: Restart the server
+      description: |
+        Stops the server so that its supervisor (for example a Kubernetes Deployment) starts it again with fresh
+        data. Only available when the server was started with `--enable-restart` (or
+        `ARCHSIGHT_RESTART_ENABLED=true`); otherwise it answers 404. When a restart token is configured it must be
+        sent in the `X-Restart-Token` header.
+      operationId: restart
+      tags:
+        - Operations
+      parameters:
+        - name: X-Restart-Token
+          in: header
+          required: false
+          description: The configured restart token (required when the server has one)
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The server shuts down
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, message]
+                properties:
+                  ok:
+                    type: boolean
+                  message:
+                    type: string
+              example:
+                ok: true
+                message: Server shutting down
+        '401':
+          description: The restart token is missing or wrong
+          content:
+            text/html:
+              schema:
+                type: string
+        '404':
+          description: The restart endpoint is not enabled
+          content:
+            text/html:
+              schema:
+                type: string
+
+  /kinds/{kind}/dot:
+    get:
+      summary: Get the graph of a kind as DOT
+      description: The GraphViz DOT graph of the resources of a kind and the relations between them.
+      operationId: getKindDot
+      tags:
+        - Graph
+      parameters:
+        - $ref: '#/components/parameters/kind'
+      responses:
+        '200':
+          description: GraphViz DOT source
+          content:
+            text/plain:
+              schema:
+                type: string
+        '404':
+          description: Unknown kind
+          content:
+            text/plain:
+              schema:
+                type: string
 
   /dot:
     get:
@@ -1343,13 +1458,11 @@ components:
               items:
                 type: string
         format:
-          type: string
-          nullable: true
+          type: [string, "null"]
           description: Rendering hint of the annotation (tag_word, tag_list, markdown, link, ...)
           example: tag_word
         type:
-          type: string
-          nullable: true
+          type: [string, "null"]
           description: Short name of the value type when the annotation declares one (Integer, Float, Time, Person, ...)
           example: Integer
 
@@ -1684,26 +1797,22 @@ components:
       type: object
       properties:
         yaml:
-          type: string
-          nullable: true
+          type: [string, "null"]
           description: Generated source text, YAML or (for pages) markdown with frontmatter (null if validation failed)
         format:
           type: string
           enum: [yaml, markdown]
           description: Format of `yaml`. Pages (kind Page) are stored as markdown files and replaced as a whole file
         errors:
-          type: array
-          nullable: true
+          type: [array, "null"]
           items:
             type: string
           description: Validation errors (null if valid)
         path_ref:
-          type: string
-          nullable: true
+          type: [string, "null"]
           description: "File path reference (edit mode only, e.g., path/file.yaml:5; just the file for markdown pages)"
         content_hash:
-          type: string
-          nullable: true
+          type: [string, "null"]
           description: Content hash (edit mode only, for optimistic locking)
 
     SaveRequest:

data/lib/archsight/web/api/routes.rb

@@ -7,6 +7,7 @@ require_relative "page_helpers"
 require_relative "requirements_helpers"
 require_relative "analysis_helpers"
 require_relative "../../assets"
+require_relative "../../openapi"
 
 module Archsight; end
 module Archsight::Web; end
@@ -220,8 +221,7 @@ module Archsight::Web::API::Routes
   # GET /api/v1/openapi.yaml - OpenAPI specification
   get "/api/v1/openapi.yaml" do
     content_type "text/yaml"
-    spec_path = File.join(__dir__, "openapi", "spec.yaml")
-    File.read(spec_path)
+    Archsight::OpenAPI.document.to_yaml
   end
 
   # Convenience aliases with .json suffix

data/lib/archsight/web/application.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "sinatra/base"
-require "kramdown"
+require_relative "../markdown"
 require "erb"
 require "fast_mcp"
 
@@ -158,7 +158,7 @@ class Archsight::Web::Application < Sinatra::Base
     # @param base [String, nil] directory of the file the markdown comes from, relative to the resources
     #   directory ("" for the root): its relative images become assets (see Archsight::Assets)
     def markdown(data, git_url: nil, base: nil, page: nil)
-      html = Kramdown::Document.new(data, input: "GFM").to_html
+      html = Archsight::Markdown.document(data).to_html
       html = Archsight::Helpers::AssetImages.rewrite(html, base_dir: base, resources_dir: Archsight.resources_dir) if base
       # ```asd blocks become placeholders until the text passes below are done (see DiagramBlocks)
       html, diagrams = Archsight::Helpers::DiagramBlocks.extract(html, resolver: Archsight::Helpers::ResourceResolver.new(db))

data/lib/archsight/web/public/vendor/redoc/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present, Rebilly, Inc. 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/lib/archsight/web/public/vendor/redoc/VERSION

@@ -0,0 +1 @@
+2.5.4

data/lib/archsight/web/public/vendor/redoc/api.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>API - Archsight</title>
+  <link rel="icon" href="/favicon.ico">
+  <style>
+    /* ReDoc brings its own styles. This page is not part of the single page app on purpose: none of the app's CSS
+       (Pico styles every <code>, headings, tables) reaches it. */
+    html, body { margin: 0; padding: 0; background: #fff; }
+    #back {
+      position: fixed; top: 12px; right: 12px; z-index: 100; padding: 6px 14px;
+      background: #fff; border: 1px solid #ddd; border-radius: 4px; box-shadow: 0 1px 4px rgba(0, 0, 0, 0.1);
+      font: 13px/1.4 system-ui, sans-serif; color: #0172ad; text-decoration: none;
+    }
+    #error { margin: 24px; font: 14px/1.4 system-ui, sans-serif; color: #c62828; }
+  </style>
+</head>
+<body>
+  <a id="back" href="/">&larr; Back</a>
+  <p id="error" role="alert" hidden></p>
+  <div id="redoc"></div>
+  <script src="/vendor/redoc/redoc.standalone.js"></script>
+  <script src="/vendor/redoc/api.js"></script>
+</body>
+</html>

data/lib/archsight/web/public/vendor/redoc/api.js

@@ -0,0 +1,19 @@
+// The API reference (/docs/api): ReDoc, vendored next to this file, renders the OpenAPI document of this server.
+(function () {
+  var back = document.getElementById('back')
+  // back to where the reader came from, the start page when this page was opened directly
+  back.addEventListener('click', function (event) {
+    if (document.referrer.indexOf(location.origin) === 0 && history.length > 1) {
+      event.preventDefault()
+      history.back()
+    }
+  })
+
+  if (!window.Redoc) {
+    var error = document.getElementById('error')
+    error.textContent = 'Failed to load ReDoc'
+    error.hidden = false
+    return
+  }
+  window.Redoc.init('/api/v1/openapi.yaml', {}, document.getElementById('redoc'))
+})()