Monkey Patching

Warning Icon

CAUTION

Advanced Technique: Monkey patching is an advanced feature and should be used with caution. It requires additional maintenance effort for the SDK and may introduce complexity.

Monkey patching allows custom code to override a module, library, or code generator. It can address bugs, add features, or implement workarounds not supported by the original source. In Speakeasy, this means modifying generated SDK code, documentation, or examples.

However, monkey patching increases maintenance effort, potentially causing inconsistencies, failures, and discrepancies in SDKs. Consider the trade-offs carefully, as it can add significant overhead.

Recommended Use Cases

Monkey patching may be beneficial in these low-impact scenarios:

  • Customizing usage snippets or example code.
  • Modifying generated documentation.
  • Encoding business logic not handled by the API.

When possible, avoid patching generated code or package dependencies, as these changes may introduce issues during SDK generation or lead to failures.

Mark Files With .genignore

To begin monkey patching, add a .genignore file to the project. This file behaves similarly to .gitignore but signals that the files it matches are managed manually rather than by the SDK generator.

Rules in .genignore follow this syntax:

  • Blank lines match nothing and improve readability.
  • Lines starting with # are comments. Escape # with a backslash (\#) to match a file starting with #.
  • Trailing spaces are ignored unless escaped with \, which preserves spaces.
  • Lines starting with ! denote negative matches (files matching that line will not be ignored).
  • Lines ending with / match directories only.
  • Text is interpreted as a glob (e.g., *.go matches all .go files).
  • Wildcards (*, ?) do not match directory separators.
  • ** matches multiple directory levels.
  • Lines starting with / match from the current directory.

Once a file is included in .genignore, the generator will no longer modify it.

Files generated by Speakeasy include the following header:

// Code generated by Speakeasy (https://www.speakeasyapi.dev). DO NOT EDIT.

To mark a file as manually maintained, update the header manually:

// Code originally generated by Speakeasy (https://www.speakeasyapi.dev).

Caveats

Monkey patching can introduce the following issues:

  • Duplicated Code: Changes in naming conventions during generation may result in duplicate symbols between patches and generated code.
  • Missing Code: Internal generator changes could lead to symbols being replaced or renamed, causing patches to break.
  • Dead Code: Patches may become obsolete if no longer referenced by the SDK, leading to unused code.

Each SDK generation event can introduce these or other maintenance challenges. It is recommended to use monkey patching only when necessary.

Recovering from Monkey Patching Issues

To resolve issues caused by monkey patching, follow these steps:

  1. Comment out the affected lines in .genignore.
  2. Regenerate the SDK using the Speakeasy CLI or GitHub Action.
  3. Compare changes between the unpatched SDK and the patched code using git diff.
  4. Modify patches as necessary, then uncomment or remove lines from .genignore to reapply the patches.
  5. Commit changes to maintain synchronization between patches and the SDK.