usk6666/yorishiro-proxy / .claude/skills/implement-plugin
implement-plugin
VerifiedScaffold, implement, and test Starlark plugins. From protocol/event/phase selection to running sample tests
/implement-plugin
A workflow skill for creating Starlark plugins on the RFC-001 §9.3 plugin engine (internal/pluginv2/). Interactively select protocol/event/phase to generate a working scaffold.
Arguments
/implement-plugin— Create a plugin in interactive mode/implement-plugin <description>— Auto-generate a plugin from a description (e.g.,/implement-plugin Add X-Request-ID header to HTTP requests)
Steps
Phase 1: Requirements Clarification
If no description argument is given, interactively confirm:
- Purpose: What should the plugin do?
- Protocol: Target plugin protocol — one of
http,ws,grpc,grpc-web,sse,raw,tls,connection,socks5(the plugin protocol vocabulary; seeinternal/pluginv2/surface.go). - Event: Hook event under that protocol (e.g.
on_request,on_message,on_chunk). - Phase:
pre_pipeline(default — before Intercept/Transform) orpost_pipeline(after; right place for signing/last-mile mutation). Lifecycle / observation events (on_close,on_handshake,on_disconnect,socks5.on_connect, etc.) take nophase=argument — passing one is a load-time error. - Action: CONTINUE (mutate in place) / DROP (transaction-start only) / RESPOND (transaction-start request; on the response side
http.on_response/ws.on_upgradeon a 101 replace the upstream response,grpc.on_start/grpc-web.on_startend the RPC).
If a description argument is given, auto-determine from its content.
Phase 2: Context Collection
Read the following to understand the plugin API:
docs/rfc/plugin-migration.md— Direct migration table from legacy hook names to(protocol, event, phase)and the rationale.internal/pluginv2/surface.go— The 17-entry hook surface table. Authoritative for which (protocol, event) pairs exist and which actions each accepts.internal/pluginv2/convert.go— The Starlarkmsgdict shape per protocol (snake_case field names,*HeadersValueordered list,msg["raw"]first-class byte injection).internal/pluginv2/lifecycle.go— Dict shapes for lifecycle events (connection.on_connect,socks5.on_connect,tls.on_handshake,ws.on_close).internal/pluginv2/respond_action.go— Typedaction.RESPOND(...)/action.RESPOND_GRPC(...)builtin signatures.examples/plugins/— Existing sample plugins for each major protocol.
Phase 3: Plugin Generation
Create a plugin file in examples/plugins/:
- Filename:
<snake_case_name>.star - Include a comment block at the top describing purpose, the
register_hookcall(s), and a config snippet - Hook registration is script-driven via
register_hook(protocol, event, fn[, phase=...])— there is noprotocol/hooksconfig key - Hook signature is
def fn(msg, ctx):— two positional arguments - Returning
Nonemeans CONTINUE;action.DROPdrops;action.RESPOND(...)short-circuits with a synthetic response (on a response-side hook it replaces the upstream response instead) - Mutate
msgin place —msg["headers"].append(name, value),msg["body"] = b"...",msg["raw"] = b"...". Mutations to the dict and to*HeadersValueare committed regardless of the return value.
Template Structure
# <Plugin Name>
#
# Purpose: <description of purpose>
#
# Hook identity (RFC-001 §9.3):
# register_hook("<protocol>", "<event>", fn[, phase="post_pipeline"])
#
# Config:
# { "path": "examples/plugins/<name>.star", "on_error": "skip" }
def <hook_name>(msg, ctx):
# Read fields: msg["method"], msg["headers"].get_first("X"), ...
# Mutate fields: msg["headers"].append("X-Foo", "bar"), msg["body"] = b"..."
return None # CONTINUE
register_hook("<protocol>", "<event>", <hook_name>)
Protocol → msg dict shape (RFC-001 §9.3 + USK-669 snake_case)
| Plugin protocol | Events | Key fields on msg |
|---|---|---|
http | on_request, on_response | method, scheme, authority, path, raw_query, status, status_reason, headers, trailers, body, anomalies (RO), raw |
ws | on_upgrade, on_message, on_close | opcode, fin, masked, mask, payload, close_code, close_reason, compressed, anomalies (RO), raw |
grpc / grpc-web | on_start, on_data, on_end | start: service, method, metadata, timeout, content_type, encoding, accept_encoding; data: service (RO), method (RO), compressed, wire_length, payload, end_stream; end: status, message, status_details, trailers |
sse | on_event | event, data, id, retry, anomalies (RO), raw |
raw | on_chunk | bytes, raw |
tls | on_handshake (lifecycle, no phase) | side, sni, alpn, version_name, cipher_name, peer_cert_subject, client_fingerprint (frozen) |
connection | on_connect, on_disconnect (lifecycle, no phase) | connect: conn_id, client_addr, listener_name; disconnect: conn_id, client_addr, duration_ms (frozen) |
| socks5 | on_connect (lifecycle, no phase) | conn_id, client_addr, target_addr (frozen) |
msg["path"] on http is the wire form on both HTTP/1.x and HTTP/2 — the request path exactly as the client sent it, percent-encoding not decoded, query excluded (USK-1139). Decode it in the plugin if a decoded view is needed.
Writing method / path / raw_query (request) or status / status_reason (response) changes the line on the wire. On HTTP/1.x only the changed parts are rebuilt — an untouched request-target is sent byte-for-byte, an absolute-form scheme://authority prefix is kept — and the values are not validated: CR / LF / SP go out verbatim, so a plugin can craft request splitting the same way it can with msg["raw"] (USK-1148). authority / scheme are not written to the HTTP/1.x wire; change the Host header instead.
headers / trailers / metadata are *HeadersValue instances, not dicts. Methods: append(name, value), delete_first(name) -> bool, replace_at(index, name, value), get_first(name) -> str|None. Iteration yields (name, value) 2-tuples; name in headers is case-insensitive. Wire order, casing, and duplicates are preserved.
ctx (second positional argument)
ctx.client_addr— client IP string (port stripped) orNonectx.tls— frozen dict of{sni, alpn, version_name, cipher_name, peer_cert_subject, client_fingerprint}orNonectx.transaction_state/ctx.stream_state— mutable scoped dicts:.get(k),.set(k, v),.delete(k),.keys(),.clear(). Lifetime is owned by the Layer (transaction = (ConnID, FlowID) for HTTP / (ConnID, StreamID) for streaming protocols; stream = (ConnID, StreamID) always).
Action constraints (RFC-001 §9.3, surface.go)
| Action | Allowed events |
|---|---|
| CONTINUE | All events (always implicit) |
| DROP | Transaction-start only: http.on_request, ws.on_upgrade, grpc.on_start, grpc-web.on_start, connection.on_connect, socks5.on_connect |
| RESPOND | Transaction-start request events (as above, minus connection/socks5), plus the response side: http.on_response and ws.on_upgrade on the upstream's 101 (replace the upstream response), and grpc.on_start / grpc-web.on_start on the upstream's response headers (end the RPC with the plugin's status). gRPC / gRPC-Web hooks must use action.RESPOND_GRPC(status, message, trailers) and HTTP / WS hooks action.RESPOND(...); the other shape is refused as CONTINUE (Warn). |
Mid-stream events (on_data, on_message, on_event, on_chunk) and lifecycle/observation events (on_close, on_end, on_handshake, on_disconnect) accept CONTINUE only — terminating a stateful stream uses native termination (gRPC RST_STREAM, WS close frame), not an action enum.
Phase 4: Verification
- Visually verify Starlark syntax (compliance with
go.starlark.netsyntax rules) - Build and run the engine load tests:
make build
make test
The engine's LoadPlugins validates register_hook calls at load time — unknown protocol/event, invalid phase, or non-callable fn are reported as LoadError with Kind = LoadErrUnknownProtocol / LoadErrUnknownEvent / LoadErrInvalidPhase / LoadErrPhaseNotSupported / LoadErrNotCallable.
Phase 5: Present Configuration Example
Present the PluginConfig for the generated plugin (RFC-001 shape — no protocol/hooks keys at the config level):
{
"path": "examples/plugins/<name>.star",
"vars": { "<key>": "<value>" },
"on_error": "skip",
"max_steps": 1000000,
"redact_keys": []
}
vars is exposed as a frozen Starlark config dict; redact_keys hides values from plugin_introspect. Plugins are loaded once at proxy boot; to change the loaded set, edit the config and restart the proxy (RFC §9.3 D2).
For runtime introspection, use the plugin_introspect MCP tool — read-only listing of loaded plugins and their (protocol, event, phase) registrations:
// MCP tool: plugin_introspect
{}
After sending test traffic through the proxy, check each plugin's fail_open_count in the same result. It counts hook outcomes the engine refused or could not evaluate and treated as CONTINUE — the message was forwarded as if the hook had not acted. last_fail_open.kind names the cause: respond_shape_mismatch (RESPOND vs RESPOND_GRPC does not match the hook's protocol), action_not_allowed (an action the event does not accept, e.g. DROP on http.on_response or ws.on_close, RESPOND on connection.on_connect), respond_on_informational, hook_error (fail() / exception / step budget), hook_timeout (still running at its deadline: the 5 s lifecycle budget, shared by all hooks of one lifecycle event so a slow earlier hook can push a later one over it, or a resend / fuzz job's timeout_ms, after which the request is aborted rather than forwarded), invalid_return (e.g. a bare "RESPOND" string), invalid_mutation, body_too_large (hook skipped for a body over 1 MiB), chunk_too_large, unsupported_message, dispatch_error. Check fail_open_by_kind rather than the total: body_too_large / unsupported_message rise on ordinary traffic even for observe-only hooks, whereas action_not_allowed, respond_*, hook_error, hook_timeout or invalid_return on a plugin that is meant to block means some of its blocking decisions were not applied. Full field reference: docs(topic="plugin_introspect").
The legacy plugin MCP tool (list/reload/enable/disable) was removed in USK-695; there is no replacement for reload/enable/disable by design.
Notes
- gRPC mid-stream events accept CONTINUE only. DROP/RESPOND on
grpc.on_data/grpc.on_endis a load-time/dispatch-time error.grpc.on_startaccepts DROP andaction.RESPOND_GRPC(...). grpc.on_start/grpc-web.on_startDROP ends the RPC with no gRPC status — RST_STREAM(CANCEL) on h2, connection close on HTTP/1.x; the upstream is not dialed. Useaction.RESPOND_GRPC(...)to answer with a status.- Response-side RESPOND replaces the upstream response.
http.on_responseRESPOND (andws.on_upgradeRESPOND on the 101) delivers the plugin's response to the client instead of the upstream's, over HTTP/1.x and HTTP/2; the exchange ends normally (keep-alive kept) and the flow records the upstream response as theoriginalvariant, the plugin's asmodified. Later hooks of the same phase are skipped, but Intercept / Transform /post_pipelinehooks still see the replacement — register withphase="post_pipeline"when the replacement must survive Transform rules. RESPOND on an informational 1xx response (e.g.103) is refused (Warn + CONTINUE); the hook fires again on the final response.ws.on_upgradeDROP on the 101 closes the client connection (HTTP/1.x) / resets the stream (HTTP/2) with no response. grpc.on_start/grpc-web.on_startalso fire on the response headers. The response-side Start has an emptymsg["service"](guard withif not msg["service"]).action.RESPOND_GRPC(...)there replaces the upstream's response with the plugin's status (Trailers-Only / gRPC-Web trailer frame) and cancels the upstream stream; DROP ends the RPC with no status, like a request-side DROP.- RESPOND must match the hook's protocol.
grpc.on_start/grpc-web.on_starttake onlyaction.RESPOND_GRPC(...);http.on_request/http.on_response/ws.on_upgradetake onlyaction.RESPOND(...). A mismatched shape is refused at dispatch time (ErrDisallowedAction): Warn log, the hook counts as CONTINUE with itsmsgedits discarded, and the request is forwarded upstream. - DROP / RESPOND are recorded (USK-1393). The stopped message is stored like any other (
queryfinds it); the Stream carries tagsplugin(your plugin's name),plugin_hook(<protocol>.<event>) andplugin_phase. DROP marks the Streamstate="error",blocked_by="plugin"(queryfilter.blocked_by: "plugin"). RESPOND / RESPOND_GRPC has noblocked_by; the plugin's response is recorded as a receive message withmetadata.synthetic = "true".http.on_responseRESPOND-replace is recorded as theoriginal/modifiedvariant pair instead. - WebSocket mid-stream events accept CONTINUE only. To redact a
ws.on_messagepayload, mutatemsg["payload"]in place rather than dropping. To refuse a connection, hookws.on_upgradeand return DROP. (socks5, on_connect)accepts DROP for connection-level allowlists, but nophase=argument — it is a lifecycle event.- WebSocket Ping/Pong frames are still delivered as
(ws, on_message)events; filter bymsg["opcode"](0x9 = ping, 0xA = pong, 0x1 = text, 0x2 = binary) when only certain frame types matter. msg["raw"] = b"..."writes verbatim wire bytes (RFC §9.3 D4 "raw wins") — when both raw and message-side fields are mutated, raw is shipped and message-side mutations are recorded only in the variant snapshot. Exception — HTTP/2 header blocks are read-only: on an HTTP/2httpmessage, agrpcon_start, and agrpc-webon_start,msg["raw"]is unframed HPACK / a header snapshot that cannot be written, so a write is ignored with a Warn (raw only → unchanged; raw + fields → the field edits apply). Editmsg["headers"]/msg["body"]/msg["metadata"]there instead.grpc/grpc-webon_datastill honourmsg["raw"](USK-1237).- Body cap:
msg["body"]is capped at 1 MiB; oversize bodies are surfaced asErrBodyTooLargeand the plugin is skipped (the body is never truncated for the plugin). - Starlark is a subset of Python:
import,class, file I/O, and network access are not available.print()writes to the proxy log. - Module-level variables are frozen after load — mutable objects (lists, dicts) at module level cannot be modified inside hooks. Use immutables (strings, ints, tuples) at module level; mutate via
msg/ctx.transaction_state/ctx.stream_state/state.*instead. configis a frozen dict ofvarsfrom the plugin config. Useconfig["key"](or membership-test first with"key" in config) — there is no schema enforcement beyond the engine's primitive type whitelist.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |