ChatGPTClaudeGrok / X / CursorGemini

DSH Plugin Resource Budgets: Four Leaks, Three Metrics

Plugin DevelopmentPublished 2026-11-17Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnessplugin developmentresource leakstimers
Plugins that leak memory or handles fail only after hours. Four resource classes, three leak metrics, and a five-step soak test.

The hardest plugin failures to catch are the ones that only appear overnight. Timers, handles, connections, and caches all look harmless in a short test, then quietly fill the heap and the descriptor table during a long run. A DSH plugin only reclaims what you register through ctx; everything else is your responsibility.

DSH plugin resources: who owns each one

Know the owner first, then you know who must act at unload. (source)

ResourceTypical originWho releases it
TimersetInterval, retry loopsYour disposer
HandleFile descriptors, child processes, streamsYour disposer
ConnectionSockets, databases, HTTP keep-aliveYour disposer
CacheMaps, indexes, dedupe setsYour plugin, at a cap

Only one column matters here. The three rows that say "your disposer" are exactly the rows the framework will not handle for you: it guarantees your disposer is called, nothing more.

The fourth row is stranger still. A cache throws no error and holds no descriptor, so it hides in plain sight. Its release is not "clear it on unload" but "cap it while running".

DSH plugin timers and polling loops

One unregistered timer becomes two, then four, with every hot reload. (source)

The danger is not the memory a timer consumes. It is the multiplication of log lines and outbound requests: save a file ten times in a debugging session and the same log message prints ten times an hour later.

Create and clear in the same ctx.effect:

  1. Start the timer inside the effect callback and close over its handle.
  2. Return a disposer that calls clearInterval and nulls the handle.
  3. Check a cancelled flag in the callback so one final tick cannot run after cleanup.
  4. Floor the poll interval; never turn a retry loop into a busy wait.

Async callbacks need one extra step. If the timer fires an async task, the disposer must await the in-flight round, otherwise a write can still land after the plugin is gone.

DSH plugin handles and connections

Open and close belong in one code block; split them across functions and you will leak. (source)

Handles and connections share a property: each has a clear open and close. The leak almost always comes from separating them -- initialization in one module, shutdown forgotten, or shutdown written into a different plugin's disposer.

Three habits that hold up:

  1. Pair immediately -- register the close the moment the resource opens, not when you remember.
  2. Bundle related resources -- one disposer for one connection pool keeps close order predictable.
  3. Close on failure -- if the fourth connection in a pool fails, close the first three before rethrowing.

That last habit is the one most often skipped. A half-built pool whose constructor throws leaves orphans that no disposer knows about.

DSH plugin caches are resources too

The cap on a cache is a budget question, not a performance question. (source)

Business caches grow with keys: one per session, one per file, one per URL. A short test sees a handful; a day of traffic sees tens of thousands, each holding a non-trivial value.

Pick one of three strategies, in increasing complexity:

  1. Fixed entry cap -- evict the oldest when full. Simplest and hardest to get wrong.
  2. Byte estimate cap -- better when values vary widely, at the cost of estimating each entry.
  3. Lifecycle cleanup -- delete keys when a session ends or a job completes, which requires a reliable end signal.

Whichever you choose, expose the current entry count as read-only state. A cache you cannot inspect is a cache without a limit.

Three DSH plugin metrics that predict a leak

You do not need an OOM to see the trend; three numbers are enough. (source)

  1. Registration count -- timers, listeners, and registered resources held by the plugin. It should return to the same level after each hot reload.
  2. Handle count -- descriptors or child processes in the host process. Flat over hours, not a staircase.
  3. Cache entries -- stable near the cap once full. A monotonic climb means eviction is not firing.

All three must be readable from the plugin's own read-only state; otherwise every investigation starts with a restart just to count things. State fields beat log lines here.

They also explain why "just restart it" is a warning sign. A restart resets every counter, hides the leak, and the next long run starts climbing from zero again.

Verification: soak test

Two steps expose what a short test hides: repeat the unload, then run long. (source)

  1. Start the plugin and record registration, handle, and cache counts as a baseline.
  2. Trigger five hot reloads in a row and assert all three return near the baseline each time.
  3. Let the plugin idle for ten minutes and assert handles do not grow with poll iterations.
  4. Push more cache keys than the cap allows and assert the entry count stays at the threshold.
  5. Unload the plugin mid-callback and assert the disposer ran and no further writes occur.

A staircase in step 2 points at a resource created outside an effect. Writes still landing in step 5 mean the cancelled flag is missing from the callback.

Disposal order and unload semantics are covered in dispose order and reverse teardown; leaks also inflate boot time, so read plugin startup cost alongside this piece.

One line to close: register every timer, handle, and connection with an effect and release them in pairs, cap every cache and make it inspectable, and watch the three counters together -- hot reload is the fastest way to amplify a leak.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Why does a DSH plugin setInterval keep running after unload?

Because the timer was never registered as a DSH plugin disposable resource. DSH plugin cleanup only covers what you register through ctx, and a bare setInterval is not part of that set. Wrap it in ctx.effect and call clearInterval inside the disposer you return.

How do I keep DSH plugin shutdown order in effect handlers?

Put the ordered work in one DSH plugin disposer. On dispose, DSH runs disposers in reverse registration order, but multiple async disposers may overlap, so stop writing before closing the connection must be sequential inside a single async disposer.

Should a DSH plugin cache be capped, and who sets it?

Yes: a DSH plugin cache should enforce its cap by entry count or bytes. DSH does not reclaim your business caches; keys grow per session, file, or URL until the cache becomes a real leak. Evicting the oldest entry at the cap is far easier to diagnose than an out-of-memory kill.

Why does DSH plugin resource usage double after a reload?

The previous instance was never drained, which is why DSH plugin usage doubles. DSH HMR disposes the old plugin, but only registered resources are cleaned; timers, connections, or listeners created outside apply or at module scope survive, so handles and connection counts climb with every save.

Related Terms

ctx.effect
ctx.effect is the registration API for a disposable resource; the disposer it returns runs when the plugin unloads, which is the right home for timers, connections, and listeners.— DeepSeek Harness Docs - Plugins and Lifecycle
Fiber
A Fiber is the lifecycle scope of one plugin instance; registrations inside it are cleaned on unload, while anything created outside the scope is not.— DeepSeek Harness Docs - Plugins and Lifecycle
dispose
dispose tears down a plugin instance: it removes registrations, unloads child plugins recursively, and resolves once every async cleanup settles.— DeepSeek Harness Docs - Plugins and Lifecycle
HMR
HMR is hot module replacement: after a source edit the old instance is disposed, registrations are cleared, and the new apply runs. Unregistered resources stay behind.— DeepSeek Harness Docs - Plugins and Lifecycle

Sources