Designing Go WeChat Mini Program Login for 50k QPS: Distributed Sessions & Async Peak Shaving

1. The Problem Isn't "How Much QPS Can Go Handle"

After a marketing campaign starts, login entry QPS can surge from hundreds to thousands or tens of thousands. The typical call chain is:

Mini Program wx.login()
  │ Temporary, one-time login code
  ▼
Gateway / Auth API
  │
  ├── WeChat auth.code2Session
  ├── MySQL identity mapping & user provisioning
  ├── Refresh Token / Session storage
  └── Return business Access Token

At this point, API pod CPU may not be high, but P99 latency degrades rapidly. The cause is usually requests waiting for WeChat HTTP calls, database connections, or Redis, not insufficient Go compute capacity. Simply scaling entry pods pushes more concurrency onto WeChat interfaces, potentially amplifying timeouts, rate limits, and one-time code invalidation.

Therefore, design and load testing must distinguish three non-interchangeable capacities:

Metric                     Definition                                              Typical Bottleneck
Entry Request QPS          Auth API received requests, including retries, polling, rejected requests   Gateway, Pod, Connection Pools
Real Login Completion TPS  Successful WeChat verification, identity mapping, session issuance           WeChat API, Database, Session System
Business Auth QPS          Business API verification of issued tokens                                 CPU, Key Distribution, Optional Redis Lookup

"50k entry QPS" does not equal "50k successful code2Session calls per second". The goal is to ensure the system can rate-limit, backpressure, fast-reject, recover, and audit when entry traffic exceeds downstream capacity, rather than assuming external dependencies have infinite capacity.

2. Separate WeChat Identity, Phone Number, and Business Session

2.1 Identity Linkage and Data Ownership

Client wx.login()
  │ Only send code via HTTPS request body to own backend
  ▼
Backend calls auth.code2Session
  │ Obtain openid, session_key, and possibly unionid when conditions met
  ▼
Map by (provider=wechat_miniprogram, appid, openid) to internal user_id
  ▼
Create device session, issue business access_token / refresh_token
  ▼
Client uses business access_token to call business APIs

openid

is the user identifier within an AppID scope. The data model should use (provider, appid, provider_user_id) as a unique key; the business system uses an immutable internal user_id. unionid is not guaranteed in all scenarios; cannot require it for login success. Cross-app account merging must go through explicit user-verified binding flows. session_key is the WeChat session key, not a business login token. It must never be returned to the client, written to ordinary logs, placed in metric labels, or used as a long-term credential.

Business sessions are server-managed security boundaries; their TTL cannot infer the availability of WeChat session_key.

2.2 Phone Number Binding Is a Separate Sensitive Data Flow

Newer Mini Program phone number flows typically have the client obtain a phone-number-specific code; the backend uses the Mini Program interface credential access_token to call the phone number API. This code differs from the wx.login code and must not be mixed. The legacy encryptedData + iv + session_key decryption should only serve explicitly supported legacy compatibility, not as the default for new systems.

Phone binding is recommended as an independent interface requiring a current business session:

POST /v1/users/phone/wechat
Authorization: Bearer <business access token>
Body: { "phone_code": "..." }

This flow should have independent timeouts, rate limits, risk control, masked logging, encrypted storage, access audit, and deletion/correction processes. Phone numbers and full query results must not be carried as plaintext Kafka event payloads.

2.3 Two Types of access_token Have Different Responsibilities

Name                          Purpose                              Storage
WeChat API access_token       Call WeChat server APIs (e.g., phone)  Server-side credential cache; never sent to Mini Program
Business access_token         Call own business APIs               Client holds short-term; server verifies signature/state

auth.code2Session

uses AppID, AppSecret, and login code; it does not require refreshing the WeChat API access_token per call. Do not treat WeChat API credentials as business JWTs, and never expose AppSecret or WeChat API credentials to the client.

3. Choose Synchronous Fast Path First, Then Decide on Async

Login is a strong interactive operation. When downstream latency and capacity are acceptable, a bounded synchronous path is simpler than "submit task → poll result" and yields shorter user wait. Async peak shaving applies only when all these conditions hold:

Burst arrival rate significantly exceeds sustainable WeChat and database processing capacity.

Client can accept brief polling or callback after 202 Accepted.

System is willing to bear task state, claim credentials, timeout recovery, and debugging complexity.

After measurement, queue wait budget remains clearly smaller than the login code validity window.

┌──────────────────────────┐
Client ────────────────► Gateway / Admission Control   │
                          └───────────┬──────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
         Synchronous Fast Path (Bounded)          Async Peak-Shaving Path (Durable)
         Global/Local Concurrency Budget                    login_job + outbox + Kafka
                    │                                   │
                    └───────────────┬───────────────────┘
                                    ▼
                         Worker's WeChat Call Concurrency Budget
                                    ▼
                              WeChat auth.code2Session
                                    ▼
                       MySQL Identity Mapping + Session/Token Issuance
                                    ▼
                 Synchronous Return or One-Time Result Claim

Kafka moves waiting from the entry to workers and makes tasks recoverable; it does not expand WeChat API capacity, nor can it make a one-time code remain valid after unlimited queuing.

4. Capacity Model: Budget for Downstream, Not Excuses for Queues

Little's Law provides a first-order estimate:

In-flight Concurrency ≈ Arrival Rate × Average Service Time

For example, if WeChat call average latency is 200 ms and target is 3,000 real logins/sec, then ~600 WeChat calls are in-flight theoretically. This ignores P99 tail latency, rate-limit responses, retries, connection pools, database writes, and safety margins. It is not proof that WeChat allows 600 concurrent calls; actual quota must be confirmed via official rules and controlled tests.

Assume downstream sustainable completion is 3,000 TPS, entry burst arrives at 5,000 TPS:

Net Backlog Rate = 5,000 - 3,000 = 2,000 task/s
30-second Cumulative Backlog = 60,000 tasks

Thus, the async path must set at least four upper bounds simultaneously:

Entry token bucket: limit submission rate per AppID, device risk tier, IP segment, or tenant.

WeChat call concurrency budget: limit globally, not just per pod.

Task queue length: reject new tasks immediately when limit reached.

Task max wait time: if estimated start time exceeds budget, mark expired; client must re-run wx.login.

On overload rejection, return explicit machine-processable responses such as 429 or 503, Retry-After, and non-sensitive error codes. Do not substitute infinite queuing for capacity decisions.

5. API Contract: Submit, Status, and Token Claim Are Separate Concerns

Clients should choose either synchronous or asynchronous as the primary flow, avoiding concurrent consumption of the same login code by two interfaces.

API                                    Semantics                              Success Response
POST /v1/auth/wechat/login             Synchronous login attempt within concurrency limit   200, returns token pair
POST /v1/auth/wechat/login-jobs        Reliably accept async login task                     202, returns task locator
GET  /v1/auth/wechat/login-jobs/{job_id} Query task status, never returns token             200, returns non-sensitive status
POST /v1/auth/wechat/login-jobs/{job_id}/claim Claim result with proof of possession        200, returns token pair
POST /v1/auth/refresh                  Atomic refresh token rotation                      200, returns new token pair
POST /v1/auth/logout                   Revoke current device session                      204

5.1 Async Claim Protocol: Prove "Same Client" Before Login Succeeds

Before login succeeds, the client has no business session, so the task result cannot be protected by "current user". Recommended: use a one-time claim secret to bind the submitter:

Client generates a 256-bit claim_secret using cryptographically secure random, keeps it only in memory; it never appears in URLs, logs, or analytics.

Client submits login_code, client_request_id, and claim_secret to the task creation endpoint.

Server generates a high-entropy, non-sequential job_id, stores only a slow hash or HMAC (with server-side key) of claim_secret with a short TTL.

Status queries return only status, suggested poll interval, and public error categories — never tokens.

On task success, client submits job_id + claim_secret to the claim endpoint. Server verifies in constant time, atomically marks result as claimed, and returns the token pair once.

Second claim must receive 409 already_claimed or equivalent without sensitive info; if client loses claim_secret, they must re-login, no bypass. job_id must have sufficient randomness but serves only as a locator, not a claim credential. All status and claim responses set Cache-Control: no-store; never put code, claim_secret, Refresh Token, or Access Token in query parameters, URLs, Referer, or client analytics events.

5.2 Idempotency and Code Consumption Rules

Login code is a one-time sensitive credential. It travels only via HTTPS request body; gateway, app, and APM must mask the field.

To prevent concurrent tasks for the same code, compute a versioned, unambiguous digest:

digest = HMAC-SHA256(active_hmac_key,
    version || length(appid) || appid || length(code) || code)

Use digest to create a unique idempotency index, and record hmac_key_id for rotation. client_request_id allows the same client to safely retry submission but must be bound to the task creation context; it cannot serve as an authentication credential alone. If the code is already associated with a task in this system, return that task's restricted status; if WeChat explicitly says code is invalid or used, client must re-call wx.login. Network timeout does not prove code was not consumed by WeChat; do not retry the same code indefinitely.

6. Persistence Model: Identity, Session, Task Each Own Their Responsibilities

6.1 MySQL: Establish Identity Facts with Unique Constraints

CREATE TABLE users (
  id BIGINT UNSIGNED NOT NULL PRIMARY KEY,
  status TINYINT NOT NULL DEFAULT 1,
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
);

CREATE TABLE user_identities (
  id BIGINT UNSIGNED NOT NULL PRIMARY KEY,
  user_id BIGINT UNSIGNED NOT NULL,
  provider VARCHAR(24) NOT NULL,
  appid VARCHAR(64) NOT NULL,
  provider_user_id VARCHAR(128) NOT NULL,
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_provider_identity (provider, appid, provider_user_id),
  KEY idx_user_id (user_id)
);

CREATE TABLE login_jobs (
  id CHAR(36) NOT NULL PRIMARY KEY,
  appid VARCHAR(64) NOT NULL,
  code_digest VARBINARY(32) NOT NULL,
  hmac_key_id VARCHAR(32) NOT NULL,
  claim_secret_hash VARBINARY(64) NOT NULL,
  state VARCHAR(24) NOT NULL,
  deadline_at DATETIME(3) NOT NULL,
  claimed_at DATETIME(3) NULL,
  error_category VARCHAR(32) NULL,
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_login_code (appid, hmac_key_id, code_digest),
  KEY idx_state_deadline (state, deadline_at)
);

Do not use application-level "check-then-insert" for identity creation. Insert identity record within a transaction; on unique key conflict, read the existing mapping. users.id generation strategy may use database sequences, Snowflake-like IDs, or other evaluated schemes, but must explicitly address global uniqueness, ordering properties, and leakage risk.

6.2 Redis: Caching, Rate Control, and Revocable State

Key Example                Content                              Constraints
auth:rate:{scope}         Token bucket / sliding window state  Limited TTL, sharded by risk dimension
auth:session:{sid}        Session state, revocation version, absolute expiry  No plaintext Refresh Token
auth:rt:{token_hash}      Refresh Token session & family state TTL equals absolute validity
wx:api-token:{appid}      WeChat API credential & refresh metadata  Proactive refresh, locking, prevent lock deletion

Critical identity, task state, and claim state should use MySQL (or equivalent durable store) as the source of truth; Redis failure must not cause task state to vanish. If legacy business requires session_key, store it isolated per WeChat session version, encrypted, short TTL, least privilege, audited; do not persist long-term keyed by openid.

7. Async Task State Machine & Failure Handling

7.1 State Definitions

State           Meaning                                      Claimable?  Next Action
PENDING         Durably accepted, awaiting publish/consume   No          Wait for Worker
RUNNING         Worker atomically claimed, processing        No          Await result or lease timeout recovery
SUCCEEDED       User mapping, session/refresh token, claim material durably written  Yes  Only successful claim once
FAILED_REAUTH   Code invalid, used, or task expired          No          Client re-runs wx.login
FAILED_RETRYABLE Pre-WeChat-call local failure safe to retry  No          Limited retry or re-queue
UNKNOWN_REAUTH  WeChat call may have completed but local commit failed  No  Do not replay original code; client re-logs in
EXPIRED         Not completed or claimed before deadline     No          Cleanup short-lived sensitive data
CLAIMED         Result successfully claimed                  No          Retain minimal audit fields then cleanup

7.2 Key Transition Principles

PENDING ──consumer claim──► RUNNING ──local commit──► SUCCEEDED ──atomic claim──► CLAIMED
  │                         │                         │
  │ deadline                │ explicit invalid code   │ claim deadline
  ▼                         ▼                         ▼
EXPIRED              FAILED_REAUTH / UNKNOWN_REAUTH  EXPIRED

Worker claim must be a conditional update, e.g., UPDATE ... WHERE state='PENDING' AND deadline_at > NOW(), to avoid duplicate WeChat calls due to Kafka redelivery.

When WeChat returns explicit invalid/used code error, transition to FAILED_REAUTH; do not automatically re-enter WeChat call for the same code.

Only brief, confirmed pre-WeChat-call local faults may transition to limited FAILED_RETRYABLE retry.

If worker crashes after WeChat response but before DB commit, cannot prove whether code was consumed. Correct choice is UNKNOWN_REAUTH or await ops intervention, not fabricate "exactly-once" guarantee. SUCCEEDED must mean user mapping, session/refresh token records, and claim material are all completed within the same recoverable boundary; otherwise claim must not be allowed.

8. Reliable Enqueue: What Transactional Outbox Solves and What It Doesn't

Using only Redis SET NX to reserve code then send Kafka creates two problems: send failure or process crash may leave reservation without task; deleting key on failure may delete another concurrent request's state.

Safer commit flow:

In a single DB transaction, write login_jobs(PENDING) and outbox_events.

After commit, Outbox Publisher continuously scans unpublished events and sends to Kafka, waiting for broker ack.

On success, mark event published; on failure, retry with backoff.

Consumer commits offset only after business result is durably persisted, and implements idempotency per task state.

Outbox guarantees "committed local tasks eventually get published", not "external WeChat call executes exactly once". Kafka transactions or exactly-once semantics cannot fold an external HTTP call into an end-to-end atomic transaction. For external side effects, explicitly design idempotency, unknown-result handling, manual investigation, and re-authentication paths.

9. Go Example: Bounded Concurrency, Global Budget, Error Classification

Below is a core boundary example, not a complete deployable project. Production implementation still needs DI, HTTP transport, DB transactions, metrics, tests, config validation, and key management.

package auth

import (
    "context"
    "errors"
    "time"
)

var ErrBusy = errors.New("wechat login capacity exhausted")

type WechatClient interface {
    Code2Session(ctx context.Context, appID, code string) (WechatSession, error)
}

type WechatSession struct {
    OpenID     string
    UnionID    string
    SessionKey string // only for controlled legacy use; never return to client
}

type GlobalLease interface {
    Acquire(ctx context.Context, resource string, ttl time.Duration) (release func(), ok bool, err error)
}

type LimitedWechatClient struct {
    inner       WechatClient
    localSlots  chan struct{}
    globalLease GlobalLease
}

func (c *LimitedWechatClient) Code2Session(ctx context.Context, appID, code string) (WechatSession, error) {
    // Respond to already cancelled requests first, avoid consuming concurrency budget.
    if err := ctx.Err(); err != nil {
        return WechatSession{}, err
    }

    select {
    case c.localSlots <- struct{}{}:
        defer func() { <-c.localSlots }()
    default:
        return WechatSession{}, ErrBusy
    }

    // Implemented by gateway quota service, fixed worker pool, or safe lease;
    // cannot rely solely on per-pod local channel to infer global limit.
    release, ok, err := c.globalLease.Acquire(ctx, "wechat-code2session", 2*time.Second)
    if err != nil {
        return WechatSession{}, err
    }
    if !ok {
        return WechatSession{}, ErrBusy
    }
    defer release()

    callCtx, cancel := context.WithTimeout(ctx, 1500*time.Millisecond)
    defer cancel()
    return c.inner.Code2Session(callCtx, appID, code)
}

HTTP Client implementation should also set total request timeout, dial and TLS handshake timeouts, idle connection count, per-host connection limit, and idle connection recycling, while maintaining connection reuse. Timeout values must be based on measured WeChat call percentiles, overall SLA, and retry strategy.

WeChat responses must validate both HTTP layer and business error fields. Network timeouts, connection resets, or gateway 5xx often mean "uncertain whether code was consumed" and should not be blindly retried; explicit invalid code, duplicate code, and other business errors can be directly classified as terminal states requiring re-authentication. Error code classification must be reviewed against current official documentation before release.

10. Business Token: Performance, Rotation, and Revocation Consistency Boundaries

Access Token should be short-lived, e.g., 10–15 minutes. It must include and strictly validate at least: iss, aud, sub, exp, iat, jti, sid, plus signature algorithm whitelist and kid mapping to keys. Using asymmetric signatures allows business services to distribute only public keys, reducing private key exposure.

Refresh Token should be a cryptographically secure random value; server stores only its hash. Refresh must atomically execute:

Validate old token not expired and not used
    ↓
Mark old token used
    ↓
Create new Refresh Token and new Access Token
    ↓
Commit and return new token pair

Transaction or Redis Lua script must ensure the same old token cannot be exchanged concurrently twice. On detected replay of old token, revoke the entire token family and require that device or all associated devices to re-login.

"Local signature verification, zero Redis lookups for all requests" and "all revocations take effect immediately" cannot both hold. Ordinary endpoints can tolerate at most one Access Token TTL of revocation propagation window; high-sensitivity endpoints (transfers, permission changes) may additionally check Redis session state or user token version. Multi-device policy must be explicit: allow coexistence, limit count, or new device evicts old; do not rely on IP or User-Agent as sole device identity.

11. Observability & SLO: Metrics Must Carry Scope

Prometheus metrics recommended per stage, keeping low-cardinality labels:

Metric                              Suggested Labels      Purpose
auth_login_requests_total           mode,result         Entry volume, rejection rate, result classification
auth_login_duration_seconds         mode                Sync/async end-to-end P50, P95, P99
wechat_code2session_duration_seconds outcome             WeChat API latency and tail degradation
wechat_code2session_total           outcome             Distinguish explicit business errors from uncertain errors
auth_login_jobs                     state               Task counts per state
auth_job_queue_age_seconds          (none or few fixed) Queue duration vs code validity risk
auth_refresh_replay_total           action              Replay attack & handling trends
auth_session_revocation_checks_total result             High-sensitivity endpoint session check load

Forbid putting openid, phone number, code, JWT, full device ID, user_id, job_id, or claim_secret into Prometheus labels. Traces only record risk-assessed correlation info; if job_id can locate a task, treat as sensitive correlation identifier, avoid sending to uncontrolled third-party analytics. Raw identity data goes into access-controlled, configurable-retention audit systems.

SLO cannot be a single "success rate". Define separately:

SLI                          Denominator                                      Example Target
Sync Service Availability    Valid requests excluding client errors & unexpected overload  Monthly ≥ 99.9%
Valid Code Login Completion  Requests within declared capacity, format & risk control pass  Report separately per WeChat dependency state
Controlled Rejection Rate    All entry requests                               Alert on threshold breach for scale/downgrade
Async Queue Wait P99         Tasks that started processing                      Less than safe proportion of code validity budget
Token Claim Failure Rate     SUCCEEDED tasks                                  Monitor client protocol or security interception issues

Must separate user cancellation, invalid input, used code, risk control rejection, server errors, and downstream failures; otherwise "success rate improvement" may just be denominator manipulation.

12. Load Testing & Chaos Drills: Evidence Over Slogans

Load tests must be split into at least three reports, not merged into one "login 50k QPS" table:

Entry Capacity Test : Mock WeChat API, keep real auth, rate limiting, task logic; test 5k, 10k, 20k, 50k entry QPS for CPU, memory, GC, P99, rejection rate, queue depth, recovery time. Report must disclose mock latency distribution vs real dependency differences.

Real Login Closed-Loop Test : Only under WeChat-allowed test conditions, legitimate quota, real network; measure real success TPS, rate-limit ratio, timeout ratio, code invalidation/consumption rate, end-to-end latency. Do not extrapolate from mock results.

Business Auth Test : Independently test JWT local verification, separately for normal endpoints and high-sensitivity endpoints with Redis revocation check.

Each report must fix and record pod count, CPU/memory limits, Go version, Redis/MySQL/Kafka config, network conditions, JWT algorithm, connection pools, traffic model, and data scale. Test matrix at minimum: step load, long steady state, burst spike, duplicate submission, pod restart, Redis failure, Kafka backlog, WeChat timeout, DB slow query, rolling deploy.

Result tables should contain only real measured values, example:

Dimension                     Baseline Measured   Target / Optimized Measured   Notes
Entry Request QPS             TBD               Target 50,000 / TBD           Includes polling & duplicate submissions
Real WeChat Login Success TPS TBD               TBD                           Constrained by WeChat external capacity
Sync Login End-to-End P99     TBD               TBD                           Specify valid request scope
Async Queue Wait P99          TBD               TBD                           Relate to code validity budget
Overload Rejection & Code Expiry Rate TBD         TBD                           Cannot exclude from failure samples
JWT Local Auth QPS            TBD               TBD                           Not equal to real login TPS

13. Go-Live Checklist & Architecture Choices

Pre-Launch Checks

Security : AppSecret and signing private keys not in DB, not in logs; Redis uses TLS/ACL; sensitive fields masked; login and phone endpoints have anti-brute, audit, alerting.

Idempotency : Covers same code concurrency, same client_request_id retry, Kafka redelivery, worker crash, claim replay, Refresh Token concurrent refresh.

Stability : Entry, Worker, WeChat call — all three layers have quotas; queue has length and age limits; safe retry vs uncertain result strictly separated.

Kubernetes : Configure readiness/liveness/startup probes; on SIGTERM stop claiming new tasks, finish or safely release in-flight leases; all state externalized during rolling deploy.

Release : Canary ratio, rollback switch, task backlog alert, WeChat error rate alert, claim failure alert, client degradation copy ready.

When Not to Introduce Kafka

If real login volume is only hundreds to thousands TPS, WeChat calls stable, MySQL unique index and connection pool healthy, synchronous path meets SLA, then "Bounded HTTP Client + Identity Mapping MySQL + Short-lived Access Token + Rotatable Refresh Token" is usually sufficient. Kafka introduces task state machine, claim protocol, client polling, validity budget, and recovery cost; should not be adopted just because of the phrase "high concurrency".

Adopt Kafka with Transactional Outbox only when traffic has clear spikes, client can tolerate brief async wait, need cross-pod durable peak shaving, and downstream capacity and recovery targets are quantified and validated. Architecture upgrade criteria should be measurable bottlenecks, risks, and recovery goals, not component count.

Conclusion

The difficulty of production-grade WeChat Mini Program login is not whether a single Go service can accept 50k HTTP requests, but how to respect the semantics of WeChat's one-time code, maintain identity uniqueness, bound external dependency concurrency, handle uncertain results of external calls, and manage session consistency between security and user experience.

A reliable solution separates entry throughput, real login completion capacity, and business auth capacity; uses synchronous fast path for normal cases, async tasks for recoverable short spikes; protects async results with one-time claim credentials; uses Outbox for local reliability while honestly facing the boundary that external side effects cannot be exactly-once. Only results accompanied by reproducible experiments and explicit metric scopes deserve the conclusion "high-concurrency login capability".

Pre-Implementation Reference Checklist

WeChat Official Docs: wx.login, Mini Program Login auth.code2Session, Phone Number getPhoneNumber and Server-side Phone API; verify parameters, permissions, quotas, error codes before release.

RFC 7519 (JWT) and RFC 8725 (JWT Best Current Practices).

Apache Kafka Official Docs: Delivery Semantics, Consumer Offsets, Transactions, and External Side-Effect Boundaries.

OpenTelemetry & Prometheus Official Docs: HTTP/RPC Semantic Conventions, Sensitive Attributes, High-Cardinality Governance.