SuperAPI AI Directory

transparent-proxy-maintenance

General & other

View repository

Updated 10-16 12:32

About this skill

transparent-proxy-maintenance

Use this skill for all paid-API lifecycle work in transparent-proxy.

Scope

Covers 3 common tasks:

  1. Modify pricing and rate limits
  2. Modify the billing method for paid APIs
  3. Add and remove paid APIs

Also includes testing + Fly deployment workflow.

Architecture you must respect

  • Core proxy: transparent-proxy/proxy.py
  • Plugin base: transparent-proxy/apis/base.py
  • One paid API per plugin file: transparent-proxy/apis/*.py
  • Static config snapshots (still kept for sync/ops):
    • transparent-proxy/config/pricing.json
    • transparent-proxy/config/rate_limits.json
    • transparent-proxy/config/proxied_apis.json
    • transparent-proxy/config/keys.json

Rule: each paid API should stay self-contained in its plugin (pricing, limit, key injection), and config snapshots must remain consistent.

Standard workflow (always)

  1. Read target plugin + related config files first.
  2. Apply minimal edits (edit_file preferred).
  3. Run tests (quick first, then full when needed).
  4. Deploy to Fly (fly deploy, no hot reload assumptions).
  5. Post-deploy smoke tests through sc-proxy.internal:8080.
  6. Verify billing headers + DB charge behavior for changed APIs.

A) Modify pricing and rate limits

Where to change

  • Plugin file, e.g. apis/twitterapi.py
    • price: pricing = Pricing.per_request(...)
    • rate limit: rate_limit = RateLimit(requests_per_minute=...)
  • Keep snapshot config aligned:
    • config/pricing.json
    • config/rate_limits.json

Example patterns

  • Per-request pricing:
    • pricing = Pricing.per_request(0.001)
  • RPM:
    • rate_limit = RateLimit(requests_per_minute=240)

Validate

  • Functional: API still returns 200 via proxy.
  • Billing headers exist on paid domains:
    • X-Credits-Used
    • X-Credits-Balance
  • Rate limit works at new threshold with burst test (expect some 429 only beyond threshold/burst).

INET/IPv6 null-safety (subscription-service specific)

When writing to subscriptions.machine_ipv6 (type INET), never pass string placeholders like "None" or "null".

  • Normalize empty/placeholder values to Python None before SQL bind.
  • Use parameterized SQL only; let psycopg2 map None to SQL NULL.
  • Expected behavior for pre-machine subscription: insert succeeds with machine_ipv6 = NULL; downstream refresh jobs should skip these rows until IPv6 is backfilled.

Stripe upgrade payment-gating (subscription-service specific)

For plan upgrades, do not switch local subscriptions.plan on change-plan response alone.

  • Treat change-plan as initiating payment only; do not persist intermediate upgrade state.
  • Only apply upgraded plan + higher daily credit after invoice.paid webhook.
  • If payment_intent_status is requires_action, return a frontend redirect/confirmation hint and keep current plan unchanged.
  • If payment is incomplete/failed (requires_payment_method, requires_confirmation, canceled), keep current plan unchanged.

This prevents unpaid/3DS-incomplete upgrades from being activated locally while keeping state handling minimal.


B) Modify the billing method for paid APIs

Available models (apis/base.py)

  • Pricing.per_request(x)
  • Pricing.per_token(input_per_1k=..., output_per_1k=...)
  • Pricing.openrouter_usage(multiplier=...)

Decision guide

  • Fixed-cost APIs → per_request
  • Token-based LLM APIs → per_token
  • OpenRouter-like responses with usage cost → openrouter_usage

Additional hooks when needed

  • extract_usage(flow) for custom token/cost extraction
  • rewrite_response(flow, credits_used, sse_streamed) for usage.cost rewrite
  • transform_sse_chunk(data) for streaming chunk rewrite
  • charge_api_type(usage) for per-model charge type (e.g. openrouter/{model})

Important implementation detail: proxy.py only calls extract_usage(...) when plugin.is_llm = True. If you implement dynamic billing via extract_usage (even for non-LLM APIs like async video), set is_llm = True in that plugin or the extracted cost will be ignored and charges become 0.

Critical checks for billing-model changes

  • Non-stream response: body.usage.cost should match X-Credits-Used when rewrite is expected.
  • SSE response: final usage chunk cost rewrite must be correct.
  • Error responses (4xx/5xx): should not create positive charges.
  • Twitterapi.io payload-shape guardrails for verification:
    • /twitter/tweet/retweeters returns users[] (not retweeters[])
    • /twitter/tweet/replies commonly returns tweets[] (not replies[])
    • /twitter/user/search returns users[] Confirm actual key shape before computing expected billed items, otherwise you may misdiagnose pricing bugs.

E) fal.ai storage support (image/video reference uploads)

When user asks to support fal image-to-video/video-to-video reference files via fal storage:

  1. Update apis/falai.py plugin to include both domains:

    • queue.fal.run (generation)
    • api.fal.ai (file storage API)
  2. Add storage endpoint handling in plugin:

    • POST /v1/serverless/files/file/local/{target_path}
    • POST /v1/serverless/files/file/url/{file}
    • optional read/list endpoints as zero-cost
  3. Enforce upload guards in plugin preflight (before upstream call):

    • Require multipart/form-data + Content-Length for local upload
    • Reject unsupported extensions
    • Enforce size limits (example policy):
      • image max 10MB
      • video max 100MB
  4. Storage pricing policy (if requested):

    • image local upload = 0.01
    • video local upload = 0.1
    • queue poll/result/list/get can remain 0
  5. Keep config snapshots/admin config aligned:

    • config/proxied_apis.json add api.fal.ai
    • config/domains.json add api.fal.ai
    • mirror to admin-app/config/* files
  6. Validation checklist:

    • unit tests for plugin endpoint identification, size limits, pricing
    • python -m py_compile on modified files
    • proxy smoke: storage upload returns billing headers (X-Credits-Used) with expected fee
  7. Abuse-prevention policy for fal integration:

    • Endpoint allowlist only (deny-by-default):
      • generation: only approved video endpoints needed for text-to-video / image-to-video / video-to-video / edit-video
      • storage: only file/local, file/url, optional file/get and list
    • Billing model scope:
      • charge generation only for per_video_second and per_video
      • unknown/unsupported generation endpoints should be rejected (403), not soft-charged with fallback
    • Storage upload anti-abuse:
      • both image and video upload operations are billable
      • enforce content-type + extension + size limits before upstream call

C) Add and remove paid APIs

Add a new paid API

  1. Create apis/<name>.py plugin class inheriting ApiPlugin.
  2. Define at minimum:
    • name
    • domains
    • env_var
    • pricing
    • inject_key(...)
  3. Add/align config snapshots:
    • config/keys.json (fake_key + env_var)
    • config/pricing.json
    • config/rate_limits.json
    • config/proxied_apis.json (domains + type)
  4. Verify plugin autoload logs show it loaded.
  5. Smoke test against a real endpoint on that domain via proxy.

Remove a paid API

  1. Remove plugin file apis/<name>.py.
  2. Remove entries from the 4 config snapshot files above.
  3. Deploy and verify:
    • Plugin no longer appears in loaded list.
    • Requests to removed domain become passthrough or unhandled as designed.
    • No new charges for removed api_type.

Testing playbook

1) Quick local/static checks

  • Read edited files to confirm exact values.
  • Run tests (start with fast suite).
  • If full suite is required, run full pytest before deploy.

2) Post-deploy smoke checks (mandatory)

Use proxy endpoint:

  • http://sc-proxy.internal:8080

For each changed API:

  • Send real request with fake key header from config.
  • Expect HTTP success and billing headers on paid API domains.

Passthrough control:

  • Test https://example.com via proxy.
  • Expect no billing headers.

3) Rate-limit verification (when RPM changed)

  • Sequential test (sanity): medium volume should pass.
  • Concurrent burst test: high volume should hit 429 near threshold/burst window.
  • Use dedicated SC-CALLER-ID for traceability.

4) Billing verification (when pricing/model changed)

  • Check X-Credits-Used precision and value shape.
  • For LLM APIs, verify rewritten cost behavior (normal + SSE).
  • Verify charges in DB for the specific caller id if needed.

Deployment (Fly)

  • Test app: test-sc-proxy with TEST_SC_PROXY_FLY_TOKEN
  • Prod app: sc-proxy with SC_PROXY_FLY_TOKEN
  • Team token file convention can be either FLY.env (workspace root) or repo-local .env; source whichever exists before deploy.

Deploy command pattern:

cd transparent-proxy
set -a; source /data/workspace/FLY.env; set +a   # or source .env
export FLY_API_TOKEN="$TEST_SC_PROXY_FLY_TOKEN"   # prod use SC_PROXY_FLY_TOKEN
fly deploy -c fly.test.toml --remote-only         # prod: fly.toml

Post-deploy checks:

  • fly status -a <app> healthy.
  • plugin load logs are clean.
  • smoke tests immediately.

Non-interactive SSH smoke tip:

  • Prefer fly ssh console --machine <id> -a <app> -C "..."
  • Avoid -s/--select in scripts (it triggers interactive prompt).

D) DB connection OOM / connection-growth triage (post-deploy)

When DB memory spikes after a deploy, check connection growth before changing billing logic.

1) Verify where connections come from (not only sc-proxy)

Use pg_stat_activity grouped by application_name, client_addr, and state.

Interpretation:

  • If one process exceeds its own pool max, suspect leak/unchecked getconn() path.
  • If each process stays near configured pool max but total is high, it's aggregate pool over-allocation across services/machines.

2) Compare against configured pool ceilings

Check pool max in each service, then sum by running machine count:

  • sc-proxy (DB_POOL_MAX)
  • starchild-credit-api (billing/user pools)
  • subscription-service (primary/user pools)
  • recharge-watcher (billing/user pools)
  • admin-app (pool)

A common failure mode is each service being “correct” individually while aggregate connections exceed DB capacity.

3) sc-proxy code audit checklist

In billing.py / proxy.py, confirm:

  • all DB access paths use with db.get_conn()
  • no direct db.pool.getconn() in request/response hot paths
  • failed/stale connections are returned with close=True
  • singleton DB object is initialized once per process

4) Immediate mitigation

  • Lower pool maxima first (fastest rollback-safe mitigation):
    • sc-proxy: reduce DB_POOL_MAX (e.g., 50 → 20)
    • also reduce secondary services' pool max where possible
  • Temporarily scale down non-critical machines (admin/aux services)
  • Redeploy and re-check pg_stat_activity

5) Completion criteria for incident

  • Total DB connections stable under expected aggregate ceiling
  • No monotonic connection growth over at least 20–30 minutes
  • DB memory remains stable after traffic bursts

Geo-restricted upstream debugging (use SC-VPN correctly)

When a target API blocks default region access, do not set global HTTP_PROXY/HTTPS_PROXY for the whole service.

  • Use SC-VPN per request only (example: http://jp:x@sc-vpn.internal:8080).
  • Keep sc-proxy as the primary path; SC-VPN is a fallback for region-specific failures.
  • Current SC-VPN fixed country codes: au,ch,de,jp,my,mx,th,za,br,ar,sg,hk,gb,nl,fr,se,es,it.
  • Unknown region returns 502 Bad Gateway; switch to one of the fixed codes above.

Guardrails

  • No hot reload assumptions; use redeploy for stable updates.
  • Prefer clean switch; avoid alias/compat hacks unless explicitly requested.
  • One change set per deploy whenever possible (easy rollback and attribution).
  • Never claim success without verifying with real proxy requests.
  • Keep plugin code minimal and isolated.

Done criteria

A change is done only when all are true:

  1. File edits match requested business change.
  2. Deploy succeeded on target Fly app.
  3. Changed API requests pass through proxy.
  4. Billing/rate-limit behavior matches requested outcome.
  5. Passthrough non-paid domains still unbilled.
  6. Results are validated with concrete request outputs.

Recommended caller-id conventions for tests

  • Chat smoke: chat:<topic>
  • Burst/rate test: chat:<api>-ratelimit
  • Pricing test: chat:<api>-pricing

This makes DB verification and incident tracing straightforward.