Return a 304 Not Modified from the /sync/:namespace/:kind/:name endpoint if nothing was built

Signed-off-by: Dominik Henneke <dominik.henneke@sda-se.com>

.changeset/techdocs-poor-forks-repeat.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-techdocs-backend': patch
+---
+
+Return a `304 Not Modified` from the `/sync/:namespace/:kind/:name` endpoint if nothing was built. This enables the caller to know whether a refresh of the docs page will return updated content (-> `201 Created`) or not (-> `304 Not Modified`).

plugins/techdocs-backend/src/DocsBuilder/builder.ts

@@ -68,7 +68,11 @@ export class DocsBuilder {
     this.config = config;
   }
 
-  public async build(): Promise<void> {
+  /**
+   * Build the docs and return whether they have been newly generated or have been cached
+   * @returns true, if the docs have been built. false, if the cached docs are still up-to-date.
+   */
+  public async build(): Promise<boolean> {
     if (!this.entity.metadata.uid) {
       throw new Error(
         'Trying to build documentation for entity not in service catalog',
@@ -125,7 +129,7 @@ export class DocsBuilder {
             this.entity,
           )} are unmodified. Using cache, skipping generate and prepare`,
         );
-        return;
+        return false;
       }
       throw new Error(err.message);
     }
@@ -205,5 +209,7 @@ export class DocsBuilder {
 
     // Update the last check time for the entity
     new BuildMetadataStorage(this.entity.metadata.uid).setLastUpdated();
+
+    return true;
   }
 }

plugins/techdocs-backend/src/service/router.ts

@@ -16,7 +16,7 @@
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { Entity, stringifyEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
-import { NotFoundError } from '@backstage/errors';
+import { NotFoundError, NotModifiedError } from '@backstage/errors';
 import {
   GeneratorBuilder,
   getLocationForEntity,
@@ -172,10 +172,10 @@ export async function createRouter({
       case 'awsS3':
       case 'azureBlobStorage':
       case 'openStackSwift':
-      case 'googleGcs':
+      case 'googleGcs': {
         // This block should be valid for all storage implementations. So no need to duplicate in future,
         // add the publisher type in the list here.
-        await docsBuilder.build();
+        const updated = await docsBuilder.build();
         // With a maximum of ~5 seconds wait, check if the files got published and if docs will be fetched
         // on the user's page. If not, respond with a message asking them to check back later.
         // The delay here is to make sure GCS/AWS/etc. registers newly uploaded files which is usually <1 second
@@ -194,10 +194,17 @@ export async function createRouter({
             'Sorry! It took too long for the generated docs to show up in storage. Check back later.',
           );
         }
+
+        if (!updated) {
+          throw new NotModifiedError();
+        }
+
         res
           .status(201)
           .json({ message: 'Docs updated or did not need updating' });
         break;
+      }
+
       default:
         throw new NotFoundError(
           `Publisher type ${publisherType} is not supported by techdocs-backend docs builder.`,