Skip to content

Update function deploy handler contract text to fetch-style#81

Merged
etbyrd merged 2 commits into
mainfrom
update-function-deploy-handler-contract-text
May 12, 2026
Merged

Update function deploy handler contract text to fetch-style#81
etbyrd merged 2 commits into
mainfrom
update-function-deploy-handler-contract-text

Conversation

@etbyrd
Copy link
Copy Markdown
Member

@etbyrd etbyrd commented May 12, 2026

Summary

The Functions tag description and the createFunction operation description in the OpenAPI spec said the handler "exports a default async function receiving the `email.received` event." That described a different runtime contract than the one Functions actually run, and that mismatch surfaced as ambiguity for anyone reading the manifest while writing a handler.

The real contract is a Workers-style fetch handler:

  • Default export is an object with an async `fetch(request, env)` method.
  • The gateway HMAC-verifies the inbound POST against the org's webhook secret before invoking `fetch`.
  • The request body parses to an `email.received` event (`EmailReceivedEvent`).

This is what the scaffolder writes (`cli-node/src/oclif/commands/functions-init.ts`), what the `CreateFunctionInput.code` schema description already says (`Must export a default { async fetch(req, env, ctx) { ... } } object.`), and what the public docs describe. The Functions tag and createFunction `description` blocks were the stale outliers.

This PR updates the OpenAPI source (`openapi/primitive-api.yaml`) in two places and regenerates the downstream artifacts (`openapi/primitive-api.codegen.json`, Node SDK generated openapi + operations + sdk.gen, Python generated client, Go generated client/handlers/server).

No code paths change; this is documentation/manifest text only.

Test plan

  • `pnpm --dir sdk-node lint`
  • `pnpm --dir sdk-node typecheck`
  • `pnpm --dir cli-node lint`
  • `pnpm --dir cli-node typecheck`
  • `pnpm --dir sdk-node generate` produces the committed artifacts (no drift)
  • No remaining occurrences of the stale phrasing across the repo

The Functions tag and createFunction operation descriptions said the
handler exports a default async function receiving the email.received
event. The actual runtime contract is a Workers-style fetch handler:
the default export is an object with an async fetch(request, env)
method, the gateway HMAC-verifies the POST against the org's webhook
secret, and the request body parses to an email.received event. Update
the OpenAPI source to match and regenerate the codegen artifacts.
@greptile-apps
Copy link
Copy Markdown

greptile-apps Bot commented May 12, 2026

Greptile Summary

This PR corrects stale documentation in the OpenAPI spec and all generated downstream artifacts — no runtime behaviour changes. The Functions tag description and createFunction operation description previously described an incorrect contract (default async function receiving email.received) and are updated to match the actual Workers-style fetch handler contract.

  • openapi/primitive-api.yaml is the only hand-edited file; all other changes are regenerated artifacts that faithfully reflect the YAML update.
  • The new text is consistent across the YAML source, codegen JSON, Go SDK (client/handlers/server/unimplemented), Node SDK (sdk.gen, openapi.generated, operations.generated), and Python client (all four function variants).

Confidence Score: 5/5

Safe to merge — every changed line is documentation text with no effect on runtime behaviour.

All ten files are either the OpenAPI source or auto-generated artifacts. The only substantive edit is correcting two description strings in primitive-api.yaml; the remaining nine files are regenerated output that mirrors those strings exactly. No code paths, schemas, types, or logic are touched.

No files require special attention.

Important Files Changed

Filename Overview
openapi/primitive-api.yaml Source of truth: updates Functions tag description and createFunction operation description to reflect the Workers-style fetch handler contract
openapi/primitive-api.codegen.json Generated codegen JSON mirrors YAML changes; description strings match the updated source exactly
sdk-go/api/oas_client_gen.go Generated Go client: doc comment on CreateFunction updated to match new contract; no logic changes
sdk-go/api/oas_handlers_gen.go Generated Go handlers: doc comment on handleCreateFunctionRequest updated; no logic changes
sdk-go/api/oas_server_gen.go Generated Go server interface: doc comment on CreateFunction updated; no logic changes
sdk-go/api/oas_unimplemented_gen.go Generated Go unimplemented handler: doc comment updated; no logic changes
sdk-node/src/api/generated/sdk.gen.ts Generated Node SDK: JSDoc comment on createFunction updated; no logic changes
sdk-node/src/openapi/openapi.generated.ts Generated Node OpenAPI document object: both Functions tag description and createFunction description updated; no logic changes
sdk-node/src/openapi/operations.generated.ts Generated Node operation manifest: createFunction description field updated; no logic changes
sdk-python/src/primitive/api/api/functions/create_function.py Generated Python client: docstrings updated consistently across all four variants (sync_detailed, sync, asyncio_detailed, asyncio); no logic changes

Reviews (2): Last reviewed commit: "Merge branch 'main' into update-function..." | Re-trigger Greptile

@etbyrd etbyrd merged commit 25cace5 into main May 12, 2026
12 checks passed
@etbyrd etbyrd deleted the update-function-deploy-handler-contract-text branch May 12, 2026 17:35
@etbyrd etbyrd mentioned this pull request May 12, 2026
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant