Implement timeout capability. Apply timeout to crypto response

[AlexLanzano]

fixes #130

Timeout Functionality: Client Perspective

1. Configuration at Init Time

When creating a client, you provide a whTimeoutConfig specifying the timeout duration and an optional callback:

whTimeoutConfig timeoutCfg = {
    .timeoutUs = WH_SEC_TO_USEC(5),   /* 5-second timeout */
    .expiredCb = myTimeoutHandler,      /* optional callback on expiry */
    .cbCtx     = myAppContext,          /* context passed to callback */
};

whClientConfig clientCfg = {
    .comm              = &commConfig,
    .respTimeoutConfig = &timeoutCfg,   /* attach timeout config */
};

wh_Client_Init(&clientCtx, &clientCfg);

During wh_Client_Init (src/wh_client.c:84-89), the config is copied into an embedded whTimeoutCtx respTimeout[1] inside the client context via wh_Timeout_Init(). This stores the timeout duration and callback but doesn't start any timer yet.

If respTimeoutConfig is NULL, the timeout context is left zeroed and effectively disabled (a timeoutUs of 0 means "never expires").

2. What Happens During a Crypto Call

Before this PR, every crypto function in wh_client_crypto.c had this pattern after sending a request:

/* Old pattern -- infinite busy-wait */
do {
    ret = wh_Client_RecvResponse(ctx, &group, &action, &res_len, dataPtr);
} while (ret == WH_ERROR_NOTREADY);

If the server never responded, the client would spin forever.

The PR replaces all ~30 of these with a single helper _recvCryptoResponse() (src/wh_client_crypto.c:165-180):

static int _recvCryptoResponse(whClientContext* ctx,
                               uint16_t* group, uint16_t* action,
                               uint16_t* size, void *data)
{
    int ret;

#ifdef WOLFHSM_CFG_ENABLE_TIMEOUT
    ret = wh_Client_RecvResponseTimeout(ctx, group, action, size, data,
                                        ctx->respTimeout);
#else
    do {
        ret = wh_Client_RecvResponse(ctx, group, action, size, data);
    } while (ret == WH_ERROR_NOTREADY);
#endif

    return ret;
}

When timeout is enabled, it delegates to wh_Client_RecvResponseTimeout. When disabled, the old infinite-loop behavior is preserved.

3. The Timeout Receive Loop

wh_Client_RecvResponseTimeout (src/wh_client.c:211-231) does this:

1. Starts the timer -- calls wh_Timeout_Start() which snapshots the current time via WH_GETTIME_US() into timeout->startUs.

2. Polls for a response -- calls wh_Client_RecvResponse() in a loop.

3. On each WH_ERROR_NOTREADY, checks wh_Timeout_Expired():

   • Gets the current time via WH_GETTIME_US()
   • Computes (now - startUs) >= timeoutUs
   • If expired: invokes the expiredCb (if set), then returns WH_ERROR_TIMEOUT
   • If not expired: loops again

4. On any other return value (success or error), returns immediately.

Client App                    _recvCryptoResponse                 wh_Timeout
    |                                |                                |
    |-- wh_Client_AesCbc() --------> |                                |
    |                                |-- wh_Timeout_Start --------> capture time
    |                                |                                |
    |                                |-- RecvResponse (NOTREADY)      |
    |                                |-- Expired? ------------------> no
    |                                |-- RecvResponse (NOTREADY)      |
    |                                |-- Expired? ------------------> no
    |                                |   ...                          |
    |                                |-- RecvResponse (NOTREADY)      |
    |                                |-- Expired? ------------------> YES
    |                                |                                |-- expiredCb()
    |<-- WH_ERROR_TIMEOUT -----------|                                |

4. What the Client Sees

From the application's perspective, the crypto APIs (wh_Client_AesCbc, wh_Client_RsaFunction, wh_Client_EccSign, etc.) now return WH_ERROR_TIMEOUT (-2010) instead of hanging indefinitely. The application can then decide how to handle it -- retry, log, fail gracefully, etc.

The expiredCb fires before the error is returned, so you can use it for logging or cleanup without needing to check the return code first.

5. Scope Limitations

A few things to note about the current design:

• Only crypto responses are covered. Non-crypto client calls (key management, NVM operations, comm init) still use the old infinite-wait pattern. The timeout is specifically wired into _recvCryptoResponse.
• The timeout is per-client, not per-call. All crypto operations for a given client share the same respTimeout context with the same duration. You can call wh_Timeout_Set(ctx->respTimeout, newValue) to change it between calls, but there's no per-operation override.

[Copilot]

Pull request overview

This PR introduces a generic timeout utility and wires client-side response timeouts into crypto operations, plus unit tests for the timeout helper.

Changes:

• Add a generic timeout module (wh_timeout.[ch]) based on WH_GETTIME_US() and expose it via configuration (WOLFHSM_CFG_ENABLE_TIMEOUT) and a new error code WH_ERROR_TIMEOUT.
• Extend whClientContext/whClientConfig and add wh_Client_RecvResponseTimeout, then route all crypto client receive paths through a new _recvCryptoResponse helper that uses the timeout when enabled.
• Add unit tests for the timeout helper and enable timeout support in the test configuration.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
wolfhsm/wh_timeout.h	Declares timeout context/config types and the timeout API used by the client; documentation establishes that timeoutUs == 0 disables the timeout.
wolfhsm/wh_settings.h	Documents WOLFHSM_CFG_ENABLE_TIMEOUT as enabling timeout helpers and client response timeouts; also defines WH_GETTIME_US(), which the timeout code relies on.
wolfhsm/wh_error.h	Introduces WH_ERROR_TIMEOUT to signal an expired timeout from client operations.
wolfhsm/wh_client.h	Adds a per-client respTimeout context, an optional respTimeout config, and declares wh_Client_RecvResponseTimeout behind WOLFHSM_CFG_ENABLE_TIMEOUT.
test/wh_test_timeout.h	Declares the whTest_Timeout unit test entry point.
test/wh_test_timeout.c	Implements unit tests for wh_Timeout_*, including callback invocation, stop/disable behavior, and bad-argument handling.
test/wh_test.c	Wires whTest_Timeout() into the unit test suite when WOLFHSM_CFG_ENABLE_TIMEOUT is defined.
test/config/wolfhsm_cfg.h	Enables WOLFHSM_CFG_ENABLE_TIMEOUT in the test configuration and ensures a valid time source via WOLFHSM_CFG_PORT_GETTIME.
src/wh_timeout.c	Implements the timeout helper functions; currently treats timeoutUs == 0 as an error in wh_Timeout_Start, which conflicts with the documented “0 disables” semantics and impacts higher-level usage.
src/wh_client_crypto.c	Introduces _recvCryptoResponse and switches all crypto receive loops to use it; with timeout support enabled this always goes through wh_Client_RecvResponseTimeout and the per-client respTimeout.
src/wh_client.c	Initializes the optional respTimeout context in wh_Client_Init and adds wh_Client_RecvResponseTimeout, which loops on WH_ERROR_NOTREADY until a valid response arrives or the timeout expires.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bigbrett]

Overall looks great. Some smaller tweaks and also proposed an extension of functionality that we might want.

[bigbrett]

two more tweaks then we should be good2go

[bigbrett]

@rizlik over to you. Please review and potentially merge