commit a49c5d98518736fd5a7d70e5e34bc042ef8e9872 · indexx.dev/bsky-alt-text-worker

+3 -23

README.md

···

       1
       1
       -
       # Cloudflare Workers OpenAPI 3.1

     

       2
       2
       -
       

     

       3
       3
       -
       This is a Cloudflare Worker with OpenAPI 3.1 using [chanfana](https://github.com/cloudflare/chanfana) and [Hono](https://github.com/honojs/hono).

     

       4
       4
       -
       

     

       5
       5
       -
       This is an example project made to be used as a quick start into building OpenAPI compliant Workers that generates the

     

       6
       6
       -
       `openapi.json` schema automatically from code and validates the incoming request to the defined parameters or request body.

     

       7
       7
       -
       

     

       8
       8
       -
       ## Get started

     

       9
       9
       -
       

     

       10
       10
       -
       1. Sign up for [Cloudflare Workers](https://workers.dev). The free tier is more than enough for most use cases.

     

       11
       11
       -
       2. Clone this project and install dependencies with `npm install`

     

       12
       12
       -
       3. Run `wrangler login` to login to your Cloudflare account in wrangler

     

       13
       13
       -
       4. Run `wrangler deploy` to publish the API to Cloudflare Workers

     

       1
       1
       +
       # Bluesky Alt Text Worker

     

       14
       2
        
       

     

       15
       15
       -
       ## Project structure

     

       3
       3
       +
       A Cloudflare Worker which works in conjunction with https://github.com/indexxing/Bluesky-Alt-Text. All endpoints are based off the original cloud function made by [symmetricalboy](https://github.com/symmetricalboy) [here](https://github.com/symmetricalboy/gen-alt-text/blob/main/functions/index.js), just in Typescript and prepackaged into a Cloudflare Worker environment.

     

       16
       4
        
       

     

       17
       17
       -
       1. Your main router is defined in `src/index.ts`.

     

       18
       18
       -
       2. Each endpoint has its own file in `src/endpoints/`.

     

       19
       19
       -
       3. For more information read the [chanfana documentation](https://chanfana.pages.dev/) and [Hono documentation](https://hono.dev/docs).

     

       20
       20
       -
       

     

       21
       21
       -
       ## Development

     

       22
       22
       -
       

     

       23
       23
       -
       1. Run `wrangler dev` to start a local instance of the API.

     

       24
       24
       -
       2. Open `http://localhost:8787/` in your browser to see the Swagger interface where you can try the endpoints.

     

       25
       25
       -
       3. Changes made in the `src/` folder will automatically trigger the server to reload, you only need to refresh the Swagger interface.

     

       5
       5
       +
       Documentation is served at the root of the worker deployment. There is a root path variable specified in the entrypoint file because my setup involves using a worker route wildcard on my custom domain.

+13 -14

src/endpoints/condense_text.ts

···

       1
       1
       -
       import { Num, OpenAPIRoute } from "chanfana";

     

       1
       1
       +
       import { Enumeration, Num, OpenAPIRoute } from "chanfana";

     

       2
       2
        
       import { z } from "zod";

     

       3
       3
        
       import { type AppContext } from "../types";

     

       4
       4
        
       

     

       5
       5
        
       export class CondenseTextEndpoint extends OpenAPIRoute {

     

       6
       6
        
       	schema = {

     

       7
       7
       -
       		tags: ["AltText"],

     

       7
       7
       +
       		tags: ["Processing"],

     

       8
       8
        
       		summary: "Condense a given text based on a directive",

     

       9
       9
        
       		security: [

     

       10
       10
        
       			{

     
···

       21
       21
        
       								required_error:

     

       22
       22
        
       									"Text is required for condensation.",

     

       23
       23
        
       							}).min(1, "Text cannot be empty."),

     

       24
       24
       -
       							directive: z.string({

     

       24
       24
       +
       							mediaType: z.enum(["video", "image"], {

     

       25
       25
        
       								description:

     

       26
       26
       -
       									"Instructions for condensing the text (e.g., 'Summarize this article', 'Extract keywords').",

     

       27
       27
       -
       								required_error:

     

       28
       28
       -
       									"A condensation directive is required.",

     

       29
       29
       -
       							}).min(1, "Directive cannot be empty."),

     

       30
       30
       -
       							targetLength: Num({

     

       31
       31
       -
       								description:

     

       32
       32
       -
       									"The approximate target length for the condensed text (e.g., number of sentences, characters, or words).",

     

       33
       33
       -
       								default: 200,

     

       34
       34
       -
       							}).optional(),

     

       26
       26
       +
       									"The type of media being described",

     

       27
       27
       +
       								required_error: "Media type is required.",

     

       28
       28
       +
       							}),

     

       35
       29
        
       						}),

     

       36
       30
        
       					},

     

       37
       31
        
       				},

     
···

       67
       61
        
       

     

       68
       62
        
       	async handle(c: AppContext) {

     

       69
       63
        
       		const data = await this.getValidatedData<typeof this.schema>();

     

       70
       70
       -
       		const { text, directive, targetLength } = data.body;

     

       64
       64
       +
       		const { text, mediaType } = data.body;

     

       65
       65
       +
       

     

       66
       66
       +
       		const targetLength = c.env.MAX_ALT_TEXT_LENGTH - 100;

     

       71
       67
        
       

     

       72
       68
        
       		try {

     

       73
       69
        
       			const res = await c.var.gemini.models.generateContent({

     
···

       75
       71
        
       				model: "gemini-2.0-flash-lite",

     

       76
       72
        
       				contents: [{

     

       77
       73
        
       					parts: [

     

       78
       78
       -
       						{ text: directive },

     

       74
       74
       +
       						{

     

       75
       75
       +
       							text:

     

       76
       76
       +
       								`You are an expert at writing concise, informative alt text. Please condense the following ${mediaType} description to be no more than ${targetLength} characters while preserving the most important details. The description needs to be accessible and useful for screen readers:`,

     

       77
       77
       +
       						},

     

       79
       78
        
       						{ text: text },

     

       80
       79
        
       					],

     

       81
       80
        
       				}],

+1 -1

src/endpoints/generate.ts

···

       48
       48
        
       

     

       49
       49
        
       export class GenerateEndpoint extends OpenAPIRoute {

     

       50
       50
        
           schema = {

     

       51
       51
       -
               tags: ["AltText"],

     

       51
       51
       +
               tags: ["Image"],

     

       52
       52
        
               summary: "Generates alt text for a given image.",

     

       53
       53
        
               security: [

     

       54
       54
        
                   {

+15 -16

src/index.ts

···

       9
       9
        
       import { Env, Variables } from "./types";

     

       10
       10
        
       

     

       11
       11
        
       const app = new Hono<{ Bindings: Env; Variables: Variables }>();

     

       12
       12
       -
       const root = "/api/altText";

     

       12
       12
       +
       

     

       13
       13
       +
       // The path which all routes are served from, for easy use with Worker Routes on custom domains.

     

       14
       14
       +
       const rootPath = "/api/altText/";

     

       13
       15
        
       

     

       14
       16
        
       app.use(

     

       15
       17
        
       	"*",

     
···

       36
       38
        
       	}),

     

       37
       39
        
       );

     

       38
       40
        
       

     

       39
       39
       -
       app.use(root + "/generate", authMiddleware);

     

       40
       40
       -
       app.use(root + "/condense_text", authMiddleware);

     

       41
       41
       -
       app.use("*", geminiMiddleware);

     

       42
       42
       -
       

     

       43
       41
        
       const openapi = fromHono(app, {

     

       44
       42
        
       	schema: {

     

       45
       43
        
       		info: {

     

       46
       46
       -
       			title: "Alt Text Generator",

     

       44
       44
       +
       			title: "Bluesky Alt Text",

     

       47
       45
        
       			description:

     

       48
       48
       -
       				"Endpoints for my Bluesky alt text generator browser extension.",

     

       46
       46
       +
       				"Endpoints for https://github.com/indexxing/Bluesky-Alt-Text",

     

       49
       47
        
       			version: "1.0",

     

       50
       48
        
       		},

     

       51
       51
       -
       		servers: [

     

       52
       52
       -
       			{

     

       53
       53
       -
       				url: "https://indexx.dev/api/altText",

     

       54
       54
       -
       			},

     

       55
       55
       -
       		],

     

       56
       49
        
       	},

     

       57
       57
       -
       	docs_url: root + "/",

     

       58
       58
       -
       	openapi_url: root + "/openapi.json",

     

       50
       50
       +
       	docs_url: rootPath,

     

       51
       51
       +
       	openapi_url: rootPath + "openapi.json",

     

       59
       52
        
       });

     

       60
       53
        
       

     

       61
       54
        
       openapi.registry.registerComponent("securitySchemes", "apiKey", {

     
···

       64
       57
        
       	in: "header",

     

       65
       58
        
       });

     

       66
       59
        
       

     

       67
       67
       -
       openapi.post(root + "/generate", GenerateEndpoint);

     

       68
       68
       -
       openapi.post(root + "/condense_text", CondenseTextEndpoint);

     

       60
       60
       +
       // Define Routes

     

       61
       61
       +
       openapi.post(rootPath + "generate", GenerateEndpoint);

     

       62
       62
       +
       openapi.post(rootPath + "condense_text", CondenseTextEndpoint);

     

       63
       63
       +
       

     

       64
       64
       +
       // Define Middlewares

     

       65
       65
       +
       app.use("*", geminiMiddleware);

     

       66
       66
       +
       app.use(rootPath + "generate", authMiddleware);

     

       67
       67
       +
       app.use(rootPath + "condense_text", authMiddleware);

     

       69
       68
        
       

     

       70
       69
        
       export default app;

+2 -2

src/middleware/auth.ts

···

       1
       1
        
       import { Context, Next } from "hono";

     

       2
       2
       -
       import { Env } from "../types";

     

       2
       2
       +
       import { Env, Variables } from "../types";

     

       3
       3
        
       

     

       4
       4
        
       export async function authMiddleware(

     

       5
       5
       -
           c: Context<{ Bindings: Env }>,

     

       5
       5
       +
           c: Context<{ Bindings: Env; Variables: Variables }>,

     

       6
       6
        
           next: Next,

     

       7
       7
        
       ) {

     

       8
       8
        
           const authToken = c.req.header("Authorization");

+6

src/types.ts

···

       6
       6
        
       export type AppContext = Context<{ Bindings: Env; Variables: Variables }>;

     

       7
       7
        
       

     

       8
       8
        
       export interface Env {

     

       9
       9
       +
       	// Environmental Variables

     

       10
       10
       +
       	MAX_ALT_TEXT_LENGTH: number;

     

       11
       11
       +
       	ABSOLUTE_MAX_LENGTH: number;

     

       12
       12
       +
       	MAX_DIRECT_BLOB_SIZE: number;

     

       13
       13
       +
       

     

       14
       14
       +
       	// Secrets

     

       9
       15
        
       	AUTH_TOKEN: string;

     

       10
       16
        
       	GEMINI_API_KEY: string;

     

       11
       17
        
       }

+6 -1

wrangler.jsonc

···

       1
       1
        
       {

     

       2
       2
        
         "$schema": "node_modules/wrangler/config-schema.json",

     

       3
       3
       -
         "name": "bluesky-alt-text-worker",

     

       3
       3
       +
         "name": "bluesky-alt-text",

     

       4
       4
        
         "main": "src/index.ts",

     

       5
       5
        
         "compatibility_date": "2025-06-07",

     

       6
       6
        
         "observability": {

     
···

       8
       8
        
           "logs": {

     

       9
       9
        
             "invocation_logs": true

     

       10
       10
        
           }

     

       11
       11
       +
         },

     

       12
       12
       +
         "vars": {

     

       13
       13
       +
           "MAX_ALT_TEXT_LENGTH": 2000,

     

       14
       14
       +
           "ABSOLUTE_MAX_LENGTH": 5000,

     

       15
       15
       +
           "MAX_DIRECT_BLOB_SIZE": 5242880

     

       11
       16
        
         }

     

       12
       17
        
       }