Sogou C++ Workflow

Connection context allows you to bind arbitrary data to a specific network connection. This is useful for stateful protocols or business logic where you need to maintain state across multiple requests on the same connection.

When to use it:

• Stateful Protocols: When implementing servers for protocols like Redis or MySQL where connection status (like a selected database) matters.
• Performance Optimization: To reduce data transmission overhead (e.g., caching large HTTP cookies on the server side so they don't need to be sent in every subsequent request on that connection).
• Lifecycle Management: You can provide a deleter function to be notified and perform cleanup when the connection is closed by the peer.

Important Limitations:

• Stateless Protocols: For standard Redis/MySQL client tasks, the framework handles connection state via the URL (username, password, DB ID). You should not use SELECT (Redis) or USE (MySQL) commands; instead, use a different URL to switch databases.
• Client Tasks: For client tasks, the connection is not determined at creation, so you can only access the connection context within a callback.

A WFModuleTask is a specialized task type used to encapsulate a group of tasks into a single logical module. Instead of manually chaining the callback of the last task in a sequence to the next functional block, you can wrap those tasks inside a module.

Key characteristics:

• Encapsulation: It provides module-level encapsulation, allowing several tasks to complete a specific function without exposing their internal logic to the parent series.
• Sub-series: A module contains a sub_series which acts as a normal SeriesWork. Tasks inside the module run within this sub-series.
• Reduced Coupling: It reduces the coupling between different functional modules by allowing tasks to interact via a shared module context rather than direct task-to-task callbacks.
• No State/Error Fields: Unlike standard tasks, WFModuleTask does not have its own state or error fields; it relies on the internal sub_series for execution state.

In Workflow, an Upstream acts as a local reverse proxy module that provides load balancing, error handling, circuit breaking, and service governance. Unlike DNS resolution, Workflow Upstream offers several advantages:

• Port Awareness: DNS is not port-aware; Upstream can manage services with the same IP but different ports.
• Address Types: While DNS only resolves to IPs, Upstream supports ip4, ip6, domain names, and unix-domain-socket.
• Real-time Updates: DNS is subject to TTL and OS/network caching; Upstream updates are real-time and take effect immediately.
• Efficiency: Upstream selection is a local computation/lookup, avoiding the higher overhead of DNS resolution.
• Protocol Agnostic: Unlike Nginx Upstream (which is primarily HTTP/HTTPS), Workflow Upstream is protocol-independent and can be used to access services like MySQL, Redis, or MongoDB.
• Zero Extra Overhead: It operates in-process, eliminating the need for an external proxy process (like Nginx) and the extra network hop associated with it.

When a request's URIHost matches an UpstreamName, the framework selects an address from that Upstream's set of recorded addresses using one of four strategies:

1. Weight random strategy: Selection is performed randomly based on the weight assigned to each address.
2. Consistent hash strategy: Uses a standard consistent hashing algorithm. Users can define a custom consistent hash function consistent_hash for the requested URI.
3. Manual strategy: Uses a user-provided select function for the requested URI. If the selected target is unavailable (blown):
   • If try_another is false: The request returns a failure.
   • If try_another is true: The framework performs a second selection using the standard consistent hash algorithm (users can also define a custom consistent_hash function here).
4. Main-backup strategy: Prioritizes 'main' servers over 'backup' servers. This strategy can be combined with any of the other three strategies.

Recommendation: Use the Consistent hash strategy for better fault tolerance and scalability. Use the Manual strategy for complex, custom selection logic.

A WFHttpServer requires a processing function of type http_process_t (which is std::function<void (WFHttpTask *)>). Inside this function, you access the request and response objects via the WFHttpTask pointer.

To handle the request:

1. Get the request and response objects: server_task->get_req() and server_task->get_resp().
2. Get the request sequence number (index of the request on the current connection) using server_task->get_task_seq().
3. Iterate through headers using protocol::HttpHeaderCursor.
4. Build the response body using append_output_body() or append_output_body_nocopy().
5. Set status codes, reason phrases, and headers (e.g., Content-Type, Connection).

void process(WFHttpTask *server_task)
{
    protocol::HttpRequest *req = server_task->get_req();
    protocol::HttpResponse *resp = server_task->get_resp();
    long seq = server_task->get_task_seq();
    
    // ... logic to read headers and append to response ...

    resp->set_status_code("200");
    resp->set_reason_phrase("OK");
    resp->add_header_pair("Content-Type", "text/html");

    // Close connection after 10 requests
    if (seq == 9) {
        resp->add_header_pair("Connection", "close");
    }
}

To create a custom communication protocol, you must inherit from protocol::ProtocolMessage and implement its virtual serialization and deserialization methods. It is highly recommended to also implement move constructors and move assignment operators to support std::move() for better performance.

Key requirements:

• Request and Response types: Must be constructible without arguments (default constructor). If retries occur, response objects may be destroyed and re-constructed, so they should ideally be RAII classes.
• Serialization: Use the encode method to prepare data for sending.
• Deserialization: Use the append method to process incoming data chunks.

namespace protocol
{
class TutorialMessage : public ProtocolMessage
{
private:
    virtual int encode(struct iovec vectors[], int max);
    virtual int append(const void *buf, size_t *size);
    virtual int append(const void *buf, size_t size);
    // ...
};

using TutorialRequest = TutorialMessage;
using TutorialResponse = TutorialMessage;
}