helper.h

Go to the documentation of this file.

/*
 * Copyright (C) 1996-2025 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */
 
/* DEBUG: section 84    Helper process maintenance */
 
#ifndef SQUID_SRC_HELPER_H
#define SQUID_SRC_HELPER_H
 
#include "base/AsyncCall.h"
#include "base/InstanceId.h"
#include "base/RefCount.h"
#include "cbdata.h"
#include "comm/forward.h"
#include "dlink.h"
#include "helper/ChildConfig.h"
#include "helper/forward.h"
#include "helper/Reply.h"
#include "helper/Request.h"
#include "helper/ReservationId.h"
#include "ip/Address.h"
#include "sbuf/SBuf.h"
 
#include <list>
#include <map>
#include <queue>
#include <unordered_map>
 
class CommTimeoutCbParams;
class MemBuf;
class Packable;
class wordlist;
 
namespace Helper
{
class Xaction {
    MEMPROXY_CLASS(Helper::Xaction);
public:
    Xaction(HLPCB *c, void *d, const char *b): request(c, d, b) {}
    Helper::Request request;
    Helper::Reply reply;
};
 
class SessionBase;
 
class Client: public RefCountable
{
public:
    using Pointer = RefCount<Client>;
 
    static Pointer Make(const char *name);
 
    virtual ~Client();
 
    Xaction *nextRequest();
 
    bool trySubmit(const char *buf, HLPCB * callback, void *data);
 
    void submitRequest(Xaction *);
 
    void packStatsInto(Packable *p, const char *label = nullptr) const;
    bool willOverload() const;
 
    void handleKilledServer(SessionBase *);
 
    void handleFewerServers(bool madeProgress);
 
    void dropQueued();
 
    void callBack(Xaction &);
 
    virtual void openSessions();
 
public:
    wordlist *cmdline = nullptr;
    dlink_list servers;
    std::queue<Xaction *> queue;
    const char *id_name = nullptr;
    ChildConfig childs; 
    int ipc_type = 0;
    Ip::Address addr;
    unsigned int droppedRequests = 0; 
    time_t overloadStart = 0; 
    time_t last_queue_warn = 0;
    time_t last_restart = 0;
    time_t timeout = 0; 
    bool retryTimedOut = false; 
    bool retryBrokenHelper = false; 
    SBuf onTimedOutResponse; 
    char eom = '\n';   
 
    struct _stats {
        int requests = 0;
        int replies = 0;
        int timedout = 0;
        int queue_size = 0;
        int avg_svc_time = 0;
    } stats;
 
protected:
    explicit Client(const char * const name): id_name(name) {}
 
    bool queueFull() const;
    bool overloaded() const;
    void syncQueueStats();
    bool prepSubmit();
    void submit(const char *buf, HLPCB * callback, void *data);
};
 
} // namespace Helper
 
// TODO: Rename to a *Client.
class statefulhelper: public Helper::Client
{
public:
    using Pointer = RefCount<statefulhelper>;
    typedef std::unordered_map<Helper::ReservationId, helper_stateful_server *> Reservations;
 
    ~statefulhelper() override = default;
 
    static Pointer Make(const char *name);
 
    void reserveServer(helper_stateful_server * srv);
 
    void cancelReservation(const Helper::ReservationId reservation);
 
    /* Helper::Client API */
    void openSessions() override;
 
private:
    friend void helperStatefulSubmit(const statefulhelper::Pointer &, const char *buf, HLPCB *, void *cbData, const Helper::ReservationId &);
 
    explicit statefulhelper(const char * const name): Helper::Client(name) {}
 
    helper_stateful_server *findServer(const Helper::ReservationId & reservation);
 
    void submit(const char *buf, HLPCB * callback, void *data, const Helper::ReservationId & reservation);
    bool trySubmit(const char *buf, HLPCB * callback, void *data, const Helper::ReservationId & reservation);
 
    Reservations reservations;
};
 
namespace Helper
{
 
class SessionBase: public CbdataParent
{
public:
    ~SessionBase() override;
 
    static void HelperServerClosed(SessionBase *);
 
    void closePipesSafely();
 
    void closeWritePipeSafely();
 
    // TODO: Teach each child to report its child-specific state instead.
    virtual bool reserved() = 0;
 
    virtual Client &helper() const = 0;
 
    virtual void dropQueued();
 
public:
    const InstanceId<SessionBase> index;
 
    int pid;
    Ip::Address addr;
    Comm::ConnectionPointer readPipe;
    Comm::ConnectionPointer writePipe;
    void *hIpc;
 
    char *rbuf;
    size_t rbuf_sz;
    size_t roffset;
 
    struct timeval dispatch_time;
    struct timeval answer_time;
 
    dlink_node link;
 
    struct _helper_flags {
        bool writing;
        bool closing;
        bool shutdown;
    } flags;
 
    using Requests = std::list<Xaction *>;
    Requests requests; 
 
    struct {
        uint64_t uses;     //< requests sent to this helper
        uint64_t replies;  //< replies received from this helper
        uint64_t pending;  //< queued lookups waiting to be sent to this helper
        uint64_t releases; //< times release() has been called on this helper (if stateful)
        uint64_t timedout; //< requests which timed-out
    } stats;
    void initStats();
};
 
class Session: public SessionBase
{
    CBDATA_CHILD(Session);
 
public:
    uint64_t nextRequestId;
 
    MemBuf *wqueue;
    MemBuf *writebuf;
 
    Client::Pointer parent;
 
    Xaction *replyXaction;
 
    bool ignoreToEom;
 
    // STL says storing std::list iterators is safe when changing the list
    typedef std::map<uint64_t, Requests::iterator> RequestIndex;
    RequestIndex requestsIndex; 
 
    ~Session() override;
 
    Xaction *popRequest(int requestId);
 
    void checkForTimedOutRequests(bool const retry);
 
    /* SessionBase API */
    bool reserved() override {return false;}
    void dropQueued() override;
    Client &helper() const override { return *parent; }
 
    static void requestTimeout(const CommTimeoutCbParams &io);
};
 
} // namespace Helper
 
// TODO: Rename to a *Session, matching renamed statefulhelper.
class helper_stateful_server: public Helper::SessionBase
{
    CBDATA_CHILD(helper_stateful_server);
 
public:
    ~helper_stateful_server() override;
    void reserve();
    void clearReservation();
 
    /* Helper::SessionBase API */
    bool reserved() override {return reservationId.reserved();}
    Helper::Client &helper() const override { return *parent; }
 
    statefulhelper::Pointer parent;
 
    // Reservations temporary lock the server for an exclusive "client" use. The
    // client keeps the reservation ID as a proof of her reservation. If a
    // reservation expires, and the server is reserved for another client, then
    // the reservation ID presented by the late client will not match ours.
    Helper::ReservationId reservationId; 
    time_t reservationStart; 
};
 
void helperSubmit(const Helper::Client::Pointer &, const char *buf, HLPCB *, void *cbData);
void helperStatefulSubmit(const statefulhelper::Pointer &, const char *buf, HLPCB *, void *cbData, uint64_t reservation);
void helperShutdown(const Helper::Client::Pointer &);
void helperStatefulShutdown(const statefulhelper::Pointer &);
 
#endif /* SQUID_SRC_HELPER_H */