archsight 0.4.3 → 0.5.0

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

@@ -374,6 +374,234 @@ paths:
         "404":
           description: Unknown colour
 
+  "/api/v1/kinds/Config/instances/{name}/preview":
+    get:
+      summary: Preview the look of a PDF Config
+      description: A fixed sample document (cover page and a page with headings, list,
+        quote, table with status badges and code) in the look of one `Config` of type
+        `pdf`, typeset by Typst like every PDF export. Served inline, for showing it
+        in a page. Only the Config shapes the result, so a changed colour, font or logo
+        is visible at once. The response carries an `ETag` (fingerprint of the document
+        and the files it is made of) and answers `304` for a matching `If-None-Match`.
+      operationId: getConfigPreview
+      tags:
+      - PDF
+      parameters:
+      - name: name
+        in: path
+        required: true
+        description: Name of the Config, e.g. `Config:PDF:default`
+        schema:
+          type: string
+      - name: part
+        in: query
+        required: false
+        description: "`cover` or `page` for a document of just that page (the viewer needs no navigation); without it both pages"
+        schema:
+          type: string
+          enum:
+          - cover
+          - page
+      - name: If-None-Match
+        in: header
+        required: false
+        description: The `ETag` of a copy the client has; a match answers `304`
+        schema:
+          type: string
+      responses:
+        '200':
+          description: The PDF
+          headers:
+            ETag:
+              schema:
+                type: string
+            Content-Disposition:
+              description: '`inline; filename="preview-<name>.pdf"`'
+              schema:
+                type: string
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+        '304':
+          description: The client's copy is current
+        '404':
+          description: No such Config
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '422':
+          description: The Config is not of type `pdf`, or the sample could not be typeset
+            (message of typst)
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '503':
+          description: typst is not installed
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+
+  "/api/v1/kinds/{kind}/instances/{name}/pdf":
+    get:
+      summary: Download a resource as PDF
+      description: |
+        Returns one resource as a PDF document, laid out by Typst (`typst` must be installed, the container image has it).
+  
+        **What it contains**: a page is exported as written (headings, tables, images, `asd` diagrams as vector graphics,
+        `[[links]]` as their label); any other resource becomes a generated document with its description,
+        properties, relations and its `architecture/diagram`. Tags steer the layout: `pdf:cover`, `pdf:toc`,
+        `pdf:landscape`, `pdf:draft`, `pdf:template:<name>` and `version:<x>`.
+  
+        **Look**: colours, fonts, logo and the texts of header and footer come from the `Config` resource of type `pdf` named
+        `default` (or the one `template` / the tag names); without one a neutral look is used.
+  
+        The response carries an `ETag` (a fingerprint of everything the PDF is made from, so a changed page, image,
+        diagram or template changes it) and answers `304` for a matching `If-None-Match`.
+      operationId: getInstancePdf
+      tags:
+      - PDF
+      parameters:
+      - "$ref": "#/components/parameters/kind"
+      - "$ref": "#/components/parameters/name"
+      - name: template
+        in: query
+        required: false
+        description: Name of a `Config` of type `pdf` to use instead of the tag or `default`
+        schema:
+          type: string
+      - name: draft
+        in: query
+        required: false
+        description: "`1` adds the draft watermark"
+        schema:
+          type: string
+          enum:
+          - '1'
+      - name: If-None-Match
+        in: header
+        required: false
+        description: The `ETag` of a copy the client has; a match answers `304`
+        schema:
+          type: string
+      responses:
+        '200':
+          description: The PDF
+          headers:
+            ETag:
+              schema:
+                type: string
+            Content-Disposition:
+              description: '`attachment; filename="<name>.pdf"`'
+              schema:
+                type: string
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+        '304':
+          description: The client's copy is current
+        '404':
+          description: Not found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '422':
+          description: The document could not be typeset (message of typst)
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '503':
+          description: typst is not installed
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+  "/api/v1/pages/{name}/pdf":
+    get:
+      summary: Download a page as PDF
+      description: |
+        Returns one page as a PDF document, laid out by Typst (`typst` must be installed, the container image has it).
+  
+        **What it contains**: a page is exported as written (headings, tables, images, `asd` diagrams as vector graphics,
+        `[[links]]` as their label); any other resource becomes a generated document with its description,
+        properties, relations and its `architecture/diagram`. Tags steer the layout: `pdf:cover`, `pdf:toc`,
+        `pdf:landscape`, `pdf:draft`, `pdf:template:<name>` and `version:<x>`.
+  
+        **Look**: colours, fonts, logo and the texts of header and footer come from the `Config` resource of type `pdf` named
+        `default` (or the one `template` / the tag names); without one a neutral look is used.
+  
+        The response carries an `ETag` (a fingerprint of everything the PDF is made from, so a changed page, image,
+        diagram or template changes it) and answers `304` for a matching `If-None-Match`.
+      operationId: getPagePdf
+      tags:
+      - PDF
+      parameters:
+      - "$ref": "#/components/parameters/name"
+      - name: template
+        in: query
+        required: false
+        description: Name of a `Config` of type `pdf` to use instead of the tag or `default`
+        schema:
+          type: string
+      - name: draft
+        in: query
+        required: false
+        description: "`1` adds the draft watermark"
+        schema:
+          type: string
+          enum:
+          - '1'
+      - name: If-None-Match
+        in: header
+        required: false
+        description: The `ETag` of a copy the client has; a match answers `304`
+        schema:
+          type: string
+      responses:
+        '200':
+          description: The PDF
+          headers:
+            ETag:
+              schema:
+                type: string
+            Content-Disposition:
+              description: '`attachment; filename="<name>.pdf"`'
+              schema:
+                type: string
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+        '304':
+          description: The client's copy is current
+        '404':
+          description: Not found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '422':
+          description: The document could not be typeset (message of typst)
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '503':
+          description: typst is not installed
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+
   /api/v1/assets/{path}:
     get:
       summary: Get an asset (image or draw.io diagram)
@@ -2120,6 +2348,8 @@ tags:
     description: Search and query operations
   - name: Pages
     description: Wiki pages (markdown with frontmatter), the page tree and the home page
+  - name: PDF
+    description: Pages and resources as PDF documents (Typst)
   - name: Assets
     description: Images and draw.io diagrams that markdown embeds
   - name: Macros

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../../pdf"
+require_relative "../../pdf/cache"
+require_relative "../../pdf/sample_document"
+
+module Archsight; end
+module Archsight::Web; end
+module Archsight::Web::API; end
+
+# Download of a page or resource as PDF
+module Archsight::Web::API::PdfHelpers
+  CACHE = Archsight::Pdf::Cache.new
+  COMPILER = Archsight::Pdf::Compiler.new
+
+  # Sends the PDF of `resource`. The ETag is the fingerprint of everything the PDF is made from, so a client (and
+  # the server's cache) keeps it exactly as long as the page, its images, diagrams and the template are unchanged.
+  # Query: `template` (name of a pdf Config), `draft=1` (watermark).
+  def serve_pdf(resource)
+    pdf_response do
+      Archsight::Pdf.document(db, resource, compiler: COMPILER, template: params[:template].to_s.empty? ? nil : params[:template],
+                                            draft: params[:draft] == "1")
+    end
+  end
+
+  # Sends the sample document in the look of a pdf Config, shown in the page instead of downloaded
+  def serve_pdf_preview(config)
+    pdf_response("inline") { Archsight::Pdf::SampleDocument.new(db, config, part: params[:part], pdf_images: COMPILER.pdf_images?) }
+  end
+
+  # Typesets the document the block builds and sends it; typst problems are answered as JSON errors
+  def pdf_response(disposition = "attachment")
+    document = yield
+    headers "X-Content-Type-Options" => "nosniff"
+    cache_control :private, :must_revalidate, max_age: 0
+    etag document.fingerprint
+    pdf = CACHE.fetch(document.fingerprint) { Archsight::Pdf.compile(document, compiler: COMPILER) }
+    content_type "application/pdf"
+    headers "Content-Disposition" => %(#{disposition}; filename="#{document.filename}")
+    pdf
+  rescue Archsight::Pdf::Unavailable => e
+    json_error(e.message, status: 503, error_type: "ServiceUnavailable")
+  rescue Archsight::Pdf::Error => e
+    json_error(e.message, status: 422, error_type: "UnprocessableEntity")
+  end
+end

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

@@ -6,6 +6,7 @@ require_relative "json_helpers"
 require_relative "page_helpers"
 require_relative "requirements_helpers"
 require_relative "analysis_helpers"
+require_relative "pdf_helpers"
 require_relative "../../assets"
 require_relative "../../openapi"
 
@@ -21,6 +22,7 @@ module Archsight::Web::API::Routes
   helpers Archsight::Web::API::PageHelpers
   helpers Archsight::Web::API::RequirementsHelpers
   helpers Archsight::Web::API::AnalysisHelpers
+  helpers Archsight::Web::API::PdfHelpers
 
   # Rendering is CPU work, previews are typed, not pasted
   MAX_DIAGRAM_SOURCE = 100_000
@@ -79,6 +81,26 @@ module Archsight::Web::API::Routes
       .merge(graph_layers: Archsight::GraphvisRenderer.default_graph_layers(instance.class.layer)))
   end
 
+  # GET /api/v1/kinds/Config/instances/:name/preview - A sample document in the look of a pdf Config (inline PDF)
+  get "/api/v1/kinds/Config/instances/:name/preview" do
+    config = db.instance_by_kind("Config", params[:name]) || db.instance_by_alias("Config", params[:name])
+    json_error("Instance '#{params[:name]}' not found", status: 404, error_type: "NotFound") unless config
+    json_error("Config '#{config.name}' is not of type #{Archsight::Pdf::Theme::TYPE}", status: 422, error_type: "UnprocessableEntity") unless config.annotations["config/type"].to_s.casecmp?(Archsight::Pdf::Theme::TYPE)
+
+    serve_pdf_preview(config)
+  end
+
+  # GET /api/v1/kinds/:kind/instances/:name/pdf - The resource as PDF document (Typst), see Archsight::Pdf
+  get "/api/v1/kinds/:kind/instances/:name/pdf" do
+    klass = Archsight::Resources[params[:kind]]
+    json_error("Kind '#{params[:kind]}' not found", status: 404, error_type: "NotFound") unless klass
+
+    instance = db.instance_by_kind(params[:kind], params[:name]) || db.instance_by_alias(params[:kind], params[:name])
+    json_error("Instance '#{params[:name]}' not found", status: 404, error_type: "NotFound") unless instance
+
+    serve_pdf(instance)
+  end
+
   # GET /api/v1/pages - Page tree built from PageMenu resources, page tags and filters and the home page
   # (shown at `/`; it is not in the tree unless a menu contains it)
   get "/api/v1/pages" do
@@ -95,6 +117,14 @@ module Archsight::Web::API::Routes
     json_response(build_page_response(page))
   end
 
+  # GET /api/v1/pages/:name/pdf - The page as PDF document (Typst), see Archsight::Pdf
+  get "/api/v1/pages/:name/pdf" do
+    page = db.instance_by_kind("Page", params[:name])
+    json_error("Page '#{params[:name]}' not found", status: 404, error_type: "NotFound") unless page
+
+    serve_pdf(page)
+  end
+
   # GET /api/v1/search - Search with query language
   get "/api/v1/search" do
     query = params[:q]

data/lib/archsight/web/public/vue/DocPage-D3QtnrmO.js

@@ -0,0 +1 @@
+import{B as e,L as t,R as n,X as r,it as i,p as a,t as o,tt as s}from"./index-BF4zUlWZ.js";import{t as c}from"./WikiPage-Bi7dzY2h.js";var l={key:1},u={__name:`DocPage`,props:{filename:String},setup(u){let d=u,f=i(null);function p(e,t){let n=new DOMParser().parseFromString(e,`text/html`).body,r=n.querySelector(`:scope > article`)||n,i=r.querySelector(`h1`),a=i?.textContent.trim()||t.split(`/`).pop().replace(/[-_]/g,` `);i?.remove();let o=[...r.querySelectorAll(`h2[id], h3[id], h4[id]`)].map(e=>({level:Number(e.tagName[1]),id:e.id,text:e.textContent.trim()})),s=[{title:`Documentation`}];return t.startsWith(`resources/`)&&s.push({title:`Resource types`}),{title:a,html:r.innerHTML,toc:o.length>=2?o:[],breadcrumb:s}}async function m(){let e=await a(d.filename);f.value=e?p(e,d.filename):{title:`Not found`,html:`<p>Documentation not found.</p>`,toc:[],breadcrumb:[{title:`Documentation`}]},o(f.value.title)}return s(()=>d.filename,m,{immediate:!0}),(i,a)=>f.value?(r(),n(c,{key:0,title:f.value.title,html:f.value.html,breadcrumb:f.value.breadcrumb,toc:f.value.toc},null,8,[`title`,`html`,`breadcrumb`,`toc`])):(r(),e(`article`,l,[...a[0]||=[t(`p`,null,`Loading...`,-1)]]))}};export{u as default};