Abstract #

Allow org admins to export one Markdown document for each RFC in their organization as part of a single click initiated batch job.

Background #

Currently RFC Hub is a monorepo with a single process handling both web rendering and API calls. Deployment kicks off via GitHub actions. Exporting RFC content would require a lot of manual copying and pasting.

Problem #

Users of RFC Hub expect the ability to export RFCs in an industry standard format to avoid vendor lockin. Supporting this will increase confidence and hopefully adoption. Since the underlying representation for RFCs is already Markdown this RFC proposes that the export process generates individual Markdown files for each RFC.

Proposal #

It could possible degrade the overall performance of the rfchub.app service if exports were to happen syncronously as part of an HTTP request. Therefore we will perform the export process, file generation, and compression of RFCs in a separate process. This separate job process will be an hourly GitHub action. The job will read from a database table, perform the export operation, and email the RFCs.

+---------------+           +---------------+                           
|               |           |               |                           
|   Monolith    |          \|   Exports     |                           
|   Server      |-----------|   Table       |                           
|               |          /|               |                           
+---------------+           +---------------+                           
                                 /|\                                    
                                  |                                     
                                  |                                     
                                  |                                     
                             +--------------+       +-------------+     
                             |              |      \|             |     
                             |   GitHub     --------|   Email     |     
                             |   Action     |      /|             |     
                             +--------------+       +-------------+     

Metadata will be attached by way of frontmatter which is a YAML preface to the Markdown document. This concept is universal and most Markdown parsers should ignore the preface.

Frontmatter Content #

Filename: RFC123: Overall title of RFC.md

---
title: "Overall title of RFC"
created: "2025-09-13T13:37:00Z"
label: "rfc123"
author: "Thomas Hunter II"
status: review
visibility: public
tags:
  - database
  - performance
watchers:
  - "Thomas Hunter II"
  - "Rupert Styx"
reviewers:
  - user: "Thomas Hunter II"
    status: approved
links:
  - rfc: "rfc123"
    type: obsoletes
---

# Synopsys

Markdown content is everything after the set of `---` characters.

User Interface #

Display a button on the org interface if the currently logged in user is an org admin. Clicking the button will add a row to the database table signaling a backup needs to happen. Create a unique constraint in the table so that only a single export row can exist at once to avoid abuse. Once the export is complete the user receives an email with the export attached.

Definition of success #

A developer will deploy the feature to prod and test it to make sure it works.

Alternatives Considered #

Do Nothing #

Nobody likes a walled garden

Export HTML #

While this format is more universal it isn't necessarily easier to convert to other formats. Conversion from Markdown would also incur additional CPU overhead.

Export .doc / .docx #

These formats are both proprietary to Microsoft but also compatible with tools like Google Docs and Open Office. Again, CPU conversion is a concern.

Export to Google Drive #

This is only useful to organizations that already have a Google account. It would also require an integration with Google APIs and require maintanence.

Perform Export in Main Server Process #

Presumably the export could be fairly fast. A user could theoretically click a link and have their download a few seconds later. That said, orgs with thousands of RFCs will bog down the system. This could be used for DDoS attacks.

Future Improvements #

Include linked materials such as images.