Incremental Builds

/**
 * FastBuilds configuration option
 * Requires the gatsby_fastbuilds Drupal module and user permissions
 */
fastBuilds: boolean;

{
  resolve: `gatsby-source-drupal`,
  options: {
    baseUrl: `https://your-site.com/`,
    basicAuth: {
      username: process.env.BASIC_AUTH_USERNAME,
      password: process.env.BASIC_AUTH_PASSWORD,
    },
    fastBuilds: true, // Requires authentication and Drupal module
  },
}

/**
 * Handles webhook updates for incremental content changes
 * @param gatsbyApi - Gatsby API functions and webhook data
 * @param pluginOptions - Plugin configuration options
 * @returns Promise that resolves when update is processed
 */
function handleWebhookUpdate(
  gatsbyApi: {
    nodeToUpdate: DrupalEntity;
    actions: {
      createNode: Function;
      unstable_createNodeManifest: Function;
    };
    cache: Cache;
    createNodeId: Function;
    createContentDigest: Function;
    getCache: Function;
    getNode: Function;
    reporter: Reporter;
  },
  pluginOptions: PluginOptions
): Promise<void>;

interface WebhookBody {
  secret?: string;
  action: 'insert' | 'update' | 'delete';
  data: DrupalEntity | DrupalEntity[];
}

// Webhook handling is automatic when webhookBody is present
// Configure webhook secret for security:
{
  resolve: `gatsby-source-drupal`,
  options: {
    baseUrl: `https://your-site.com/`,
    secret: process.env.PREVIEW_SECRET, // Must match Drupal configuration
  },
}

// Webhook request format from Drupal:
{
  "secret": "your-shared-secret",
  "action": "update",
  "data": {
    "id": "article-123",
    "type": "node--article",
    "attributes": { /* updated content */ },
    "relationships": { /* entity relationships */ }
  }
}

/**
 * Handles deletion of nodes and cleanup of relationships
 * @param options - Configuration for deletion handling
 * @returns Promise resolving to the deleted node
 */
function handleDeletedNode(options: {
  actions: Actions;
  node: DrupalEntity;
  getNode: Function;
  createNodeId: Function;
  createContentDigest: Function;
  cache: Cache;
  entityReferenceRevisions: string[];
  pluginOptions: PluginOptions;
}): Promise<GatsbyNode>;

/**
 * Creates node manifests for Gatsby Cloud Preview support
 * @param options - Manifest creation configuration
 */
function drupalCreateNodeManifest(options: {
  attributes: DrupalEntityAttributes;
  gatsbyNode: GatsbyNode;
  unstable_createNodeManifest: Function;
}): void;

// Preview is automatically enabled in development with refresh endpoint
process.env.NODE_ENV === 'development' && 
process.env.ENABLE_GATSBY_REFRESH_ENDPOINT

// Or explicitly enabled with:
process.env.GATSBY_IS_PREVIEW === 'true'

/**
 * Creates node if it doesn't exist (for webhook updates and references)
 * @param options - Node creation configuration
 * @returns Promise that resolves when node is created or already exists
 */
function createNodeIfItDoesNotExist(options: {
  nodeToUpdate: DrupalEntity;
  actions: Actions;
  createNodeId: Function;
  createContentDigest: Function;
  getNode: Function;
  reporter: Reporter;
  pluginOptions: PluginOptions;
}): Promise<void>;

GET /gatsby-fastbuilds/sync/{timestamp}

{
  "status": 1,
  "timestamp": 1623456789,
  "entities": [
    {
      "action": "update",
      "data": { /* entity data */ }
    },
    {
      "action": "delete", 
      "data": { "id": "node-123", "type": "node--article" }
    }
  ]
}

// Expired or missing timestamp
if (res.body.status === -1) {
  reporter.info('Unable to pull incremental data changes from Drupal');
  setPluginStatus({ lastFetched: res.body.timestamp });
  requireFullRebuild = true;
}

// Network or API errors trigger full rebuild
catch (error) {
  reporter.warn('FastBuilds request failed, falling back to full build');
  requireFullRebuild = true;
}

// Legacy endpoint (deprecated)
app.use('/___updatePreview/', bodyParser.text(), async (req, res) => {
  // Handle preview updates
});

// Modern approach uses Gatsby's refresh endpoint
// Configure in Drupal to POST to: http://localhost:8000/__refresh

// Validate webhook secret
if (pluginOptions.secret && pluginOptions.secret !== secret) {
  reporter.warn('The secret in this request did not match your plugin options secret.');
  return;
}

// Validate webhook structure
if (!action || !data) {
  reporter.warn('The webhook body was malformed');
  return;
}

// Webhook can contain single entity or array
let nodesToUpdate = data;
if (!Array.isArray(data)) {
  nodesToUpdate = [data];
}

// Process each entity
for (const nodeToUpdate of nodesToUpdate) {
  await handleWebhookUpdate(/* ... */);
}

// Touch existing nodes during incremental builds
getNodes().forEach(node => {
  if (node.internal.owner === 'gatsby-source-drupal') {
    touchNode(node);
  }
});

// Cache referenced nodes
await cache.set(`refnodes-${node.id}`, referencedNodes);

// Cache back-reference field names
await cache.set(`backrefs-${node.id}`, backRefsNames);

// Process multiple webhook updates concurrently
await Promise.all(nodesToUpdate.map(async (nodeToUpdate) => {
  await handleWebhookUpdate(/* ... */);
}));

// Manifest creation for preview routing
const manifestId = `${id}-${updatedAt}-${langcode}`;
unstable_createNodeManifest({
  manifestId,
  node: gatsbyNode,
  updatedAtUTC: updatedAt,
});

interface WebhookBody {
  secret?: string;
  action: 'insert' | 'update' | 'delete';
  data: DrupalEntity | DrupalEntity[];
}

interface FastBuildsResponse {
  status: number; // 1 for success, -1 for expired/error
  timestamp: number;
  entities: FastBuildsEntity[];
}

interface FastBuildsEntity {
  action: 'insert' | 'update' | 'delete';
  data: DrupalEntity | { id: string; type: string };
}

interface NodeManifestOptions {
  manifestId: string;
  node: GatsbyNode;
  updatedAtUTC: string;
}