Web API#

Oasis는 HTTP, HTTPS 서버와 클라이언트를 지원합니다.

헤더 파일#

OasisWeb.h

HttpUpStreamDelegate 인터페이스#

Oasis Web 서버와 클라이언트는 HttpUpStreamDelegate 인터페이스로 부터 유도된 사용자 정의 객체를 통하여 HTTP 요청과 응답을 처리합니다.

class HttpUpStreamDelegate : public std::enable_shared_from_this<HttpUpStreamDelegate>
{
public:
    HttpUpStreamDelegate();
    virtual ~HttpUpStreamDelegate();

public: 
    virtual void onRequest(const NetMessageRef &msg);
    virtual void onEarlyResponse(const NetMessageRef &msg); //when the response header is ready
    virtual void onResponse(const NetMessageRef &msg); //when the response header and contents ready
    virtual void onGatewayResponse(const struct sockaddr_in &local_addr, const struct sockaddr_in &remote_addr, int32_t status_code, const char *status_reason, const char *content_type, const char *content, size_t content_length, key_value_map_t &parameters);
};

웹 서버 함수#

HTTPS를 활성화하려면 아래 key-value map이 필요합니다.

아래는 웹소켓 서비스 생성에 필요한 key-value map 목록입니다.

아래 코드는 웹 문서 확장자가 osp인 경우, 웹 서버 스크립트 수행하는 예입니다.

static int32_t httpInterpretCallback(const char *url, void *callback_data, key_value_map_t *callback_arguments, const char *key_name, std::string &output)
{
    // key_name에 해당하는 값을 구하여 output에 리턴합니다.
    return 0;
}

void MyHttpConfigUpStreamDelegate::onRequest(const NetMessageRef &msg)
{
    bool reply_now = true;
    std::string url;
    netMessageUriGetPath(msg, url);

    ASSERT(netMessageIsRequest(msg));
    if(!netMessageIsRequest(msg)) {
        return;
    }

    NetMessageRef res = netMessageCreate(msg, false);
    if(res == nullptr) {
        netMessageAbortConnection(msg);
        return;
    }

    netMessageSetStatusCodeAndReasonString(res, 200, "OK");
    netMessageSetHeaderField(res, "Connection", "close");

    if(url == "/") {

        std::string index_path = app().httpRootPath();
        index_path += "/index.osp";
        err = httpInterpretServerPage(res, url.c_str(), index_path.c_str(), &httpInterpretCallback, (void*)this, nullptr);
        if(err < 0) {
            //do nothing
            netMessageAbortConnection(msg);
            return;
        }
    } else {

        std::string path = app().httpRootPath();
        path += url;
        if(access(path.c_str(), F_OK) == 0) {
            //get mime type based on extension
            const char *mime_type = get_file_mime_type(path.c_str());   
            if(mime_type == nullptr) {
                //not supported
                netMessageSetStatusCodeAndReasonString(res, 403, "Forbidden");
            } else {
                std::string ext = get_file_ext(path);
                if(ext == "osp") {
                    err = httpInterpretServerPage(res, url.c_str(), path.c_str(), &httpInterpretCallback, (void*)this, nullptr);
                    if(err < 0) {
                        //do nothing
                        netMessageAbortConnection(msg);
                        return;
                    }
                } else {
                    ssize_t ret = netMessageSendFile(res, path.c_str(), mime_type);
                    reply_now = false;
                }
            }
        } else {
            netMessageSetStatusCodeAndReasonString(res, 400, "Bad Request");
        }
    }

done:
    if(reply_now) {
        netMessagePost(res);    
    }
}

Script 처리 콜백#

Oasis 웹 서버는 웹 문서 내에 <?=<key_name>?> 양식의 서버 스크립트용 요소를 정의할 수 있습니다.

httpInterpretServerPage 함수는 웹 문서에서 이 요소를 분류하여, <key_name>에 해당하는 실제 값을 http_interpret_callback_t 콜백 함수를 호출하여 얻습니다. 이렇게 동적으로 변경한 웹 문서 내용을 클라이언트에게 전달합니다.

아래는 http_interpret_callback_t 구현 예입니다.

<p>
    제품명은 <?=printProductName?> 입니다.
</p>  
<p>
    접속한 서버의 IP 주소는 <?=printIPAddress?> 입니다.
</p>

static int32_t httpInterpretCallback(const char *url, void *callback_data, key_value_map_t *callback_arguments, const char *key_name, std::string &output)
{
    std::string  _url(url);
    char value[256];
    int32_t err;

    output.clear();

    if(strcmp(key_name, "printProductName") == 0) {
        output = "Oasis";
    } else if(strcmp(key_name, "printIPAddress") == 0) {
        output = "127.0.0.1";
    }

    return 0;
}

웹 클라이언트 함수#

연결에 필요한 key-value map은 아래와 같습니다.

예제#

서버#

아래 예제의 서버는 홈 페이지에 접속하면 index.osp 파일을 읽어서 Script 콜백 함수를 호출하여 index.osp 내에 있는 변수값을 실제 적용 값으로 치환하여 클라이언트에게 전송합니다. 그외 파일에 접근할 경우, 허용된 경우에 파일 내용을 전송합니다.

또한 /ws/echo 에 웹소켓 서버를 연결하여, 웹소켓 클라이언트가 /ws/echo URL에 접속할 경우, 웹소켓 통신을 하게 됩니다.

응용 프로그램 이름은 webserver 이고 사용법은 아래와 같습니다.

USAGE: ./webserver  [-p <port number>] [-s] <documnet root dir>
$ ./webserver -p 8080 -s /mnt/sd

• p 옵션은 포트번호를 지정합니다.
• s 옵션은 보안 서버 (HTTPS)를 실행합니다. 인증서와 개인키는 각 /mnt/sd/webserver-cert.pem 와 /mnt/sd/webserver-key.pem 에 있다고 가정합니다.
• documnet root dir 필수 인자로서 HTTP 문서 파일들의 루트 디렉토리 경로입니다.

코드를 설명합니다.

서버에서 스크립트 콜백 함수를 정의합니다.

static int32_t httpInterpretCallback(const char *url, void *callback_data, key_value_map_t *callback_arguments, const char *key_name, std::string &output)
{
    std::string  _url(url);
    char value[256];
    int32_t err;

    output.clear();

    if(strcmp(key_name, "printModelName") == 0) {
        output = "OASIS";
    }  

    return 0;
}

HTTP 서버용 HttpUpStreamDelegate 에서 유도된 사용자 정의 Delegate 클래스를 정의합니다.

class MyHttpUpStreamDelegate : public HttpUpStreamDelegate 
{
public:
    MyHttpUpStreamDelegate() { }
    virtual ~MyHttpUpStreamDelegate() { }

public:
    virtual void onRequest(const NetMessageRef &msg) {

        std::string url;
        netMessageUriGetPath(msg, url);

        ASSERT(netMessageIsRequest(msg));
        if(!netMessageIsRequest(msg)) {
            return;
        }

        NetMessageRef res = netMessageCreate(msg, false);
        if(res == nullptr) {
            netMessageAbortConnection(msg);
            return;
        }    

        fprintf(stdout, "onRequest: %s\n", url.c_str());

        netMessageSetStatusCodeAndReasonString(res, 200, "OK");
        //netMessageSetHeaderField(res, "Connection", "close");

        if(url == "/") {
            // HOME url이면, HTTP 문서의 루트 디렉토리에 index.osp 파일을 읽어와 스크립트를 실행 후 전송합니다.
            std::string index_path = http_root_dir_path + "/index.osp";
            int32_t err = httpInterpretServerPage(res, url.c_str(), index_path.c_str(), &httpInterpretCallback, (void*)this, nullptr);
            if(err < 0) {
                netMessageAbortConnection(msg);
                return;
            } else {
                netMessagePost(res);    
            }

        } else {
            std::string path = http_root_dir_path + url;
            if(access(path.c_str(), F_OK) == 0) {
                //get mime type based on extension
                const char *mime_type = get_file_mime_type(path.c_str());   
                if(mime_type == nullptr) {
                    //not supported
                    netMessageSetStatusCodeAndReasonString(res, 403, "Forbidden");
                    netMessagePost(res);    
                } else {
                    std::string ext = get_file_ext(path);
                    if(ext == "osp") {
                        //oasis server script file extension
                        int32_t err = httpInterpretServerPage(res, url.c_str(), path.c_str(), &httpInterpretCallback, (void*)this, nullptr);
                        if(err < 0) {
                            netMessageAbortConnection(msg);
                            return;
                        }
                    } else {
                        netMessageSendFile(res, path.c_str(), mime_type);
                    }
                }
            } else {
                netMessageSetStatusCodeAndReasonString(res, 400, "Bad Request");
                netMessagePost(res);    
            }
        }
    }

    virtual void onResponse(const NetMessageRef &msg) {

    }
};

index.osp 문서는 아래와 같습니다.

<html>
<head>
<meta charset="utf-8">
<title>Oasis Web Server</title>
</head>
<body>
<h1> Hello, World!</h1>
<h2> My model is <?=printModelName?>.</h2>
</body>
</html>

웹소켓 서버용 WsEventDelegate 에서 유도된 사용자 정의 Delegate 클래스를 정의합니다. 단순 받은 메세지를 그대로 응답하는 기능입니다.

class EchoWsEventDelegate : public WsEventDelegate
{
public:
    EchoWsEventDelegate() {}
    virtual ~EchoWsEventDelegate() {}

public: 
    virtual void onOpen(const WsEventRef &evt) {
        fprintf(stdout, "Echo: Open\n");
    }

    virtual void onMessage(const WsEventRef &evt)  {
        fprintf(stdout, "Echo: Message\n");

        if(wsEventMessageType(evt) == kWsMessageText) {
            std::vector<uint8_t> data;
            if(wsEventData(evt, data) > 0) {
                std::string str = "Echo: ";
                str += std::string(data.data(), data.data()+data.size());
                wsSendText(evt, str.c_str());
            }
        }
    }

    virtual void onError(const WsEventRef &evt) {
        fprintf(stdout, "Echo: Error\n");
    }

    virtual void onClose(const WsEventRef &evt) {
        fprintf(stdout, "Echo: Close\n");
    }
};

Oasis를 초기화 합니다. Oasis 파일 시스템을 사용하지 않습니다.

    key_value_map_t parameters;

    parameters["offs-disable"] = "1";
    if(oasis::initialize(parameters) < 0) {
        fprintf(stderr,  "Oasis init failed\n");
        return -1;
    }

HTTP 서버 객체를 생성하고 시작합니다.

    parameters.clear();

    parameters["port"] = std::to_string(http_port);
    parameters["root-dir"] = http_root_dir_path.c_str();
    parameters["content-length-max"] = std::to_string(3*1024*1024);

    parameters["tls-disable-certificate-validation"] = "1";

    if(is_secure) {
        parameters["tls-enabled"] = "1";
        parameters["tls-version"] = "1.2";

        parameters["cert-file-path"] = "/mnt/sd/webserver-cert.pem";
        parameters["pkey-file-path"] = "/mnt/sd/webserver-key.pem";
    }

    http_delegate = std::make_shared<MyHttpUpStreamDelegate>();

    http_server = oasis::createHttpServer(parameters, http_delegate);
    if (http_server) {
        err = oasis::startHttpServer(http_server);
        ASSERT(err == 0);
        if(err < 0) {
            fprintf(stderr,  "HTTPS server failed\n");
            goto done;
        }
        fprintf(stdout, "HTTP%s running at %d...\n", is_secure?"S":"", http_port);

        // 웹소켓 서비스를 /ws/echo URL을 통해 접근하도록 합니다.
        parameters.clear();
        std::shared_ptr<EchoWsEventDelegate> echo_delegate = std::make_shared<EchoWsEventDelegate>();
        if(createHttpWsService(http_server, "/ws/echo", parameters, echo_delegate) >= 0) {
        }
    }

HTTP 서버를 해제합니다.

    if(http_server) {
        oasis::destroyHttpServer(http_server);
    }

전체 코드는 아래와 같습니다.

#include "OasisAPI.h"
#include "OasisWeb.h"
#include "OasisLog.h"
#include "OasisUtil.h"

#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <dirent.h>

#include <signal.h>

#include <thread>
#include <mutex>
#include <memory>
#include <condition_variable>

#define DLOG_THIS   0x00080000

#undef DLOG_FLAGS
#define  DLOG_FLAGS (DLOG_FLAGS_DEFAULT|DLOG_THIS/**/)

#undef DLOG_TAG
#define DLOG_TAG "HTTP-SERVER"


using namespace oasis;

static bool isDirectory(const char *path)
{
    struct stat path_stat;
    stat(path, &path_stat);
    return S_ISDIR(path_stat.st_mode);
}

static std::string http_root_dir_path;


static int32_t httpInterpretCallback(const char *url, void *callback_data, key_value_map_t *callback_arguments, const char *key_name, std::string &output)
{
    std::string  _url(url);
    char value[256];
    int32_t err;

    output.clear();

    if(strcmp(key_name, "printModelName") == 0) {
        output = "OASIS";
    }  

    return 0;
}


class MyHttpUpStreamDelegate : public HttpUpStreamDelegate 
{
public:
    MyHttpUpStreamDelegate() { }
    virtual ~MyHttpUpStreamDelegate() { }

public:
    virtual void onRequest(const NetMessageRef &msg) {

        std::string url;
        netMessageUriGetPath(msg, url);

        ASSERT(netMessageIsRequest(msg));
        if(!netMessageIsRequest(msg)) {
            return;
        }

        NetMessageRef res = netMessageCreate(msg, false);
        if(res == nullptr) {
            netMessageAbortConnection(msg);
            return;
        }    

        fprintf(stdout, "onRequest: %s\n", url.c_str());

        netMessageSetStatusCodeAndReasonString(res, 200, "OK");
        //netMessageSetHeaderField(res, "Connection", "close");

        if(url == "/") {

            std::string index_path = http_root_dir_path + "/index.osp";
            int32_t err = httpInterpretServerPage(res, url.c_str(), index_path.c_str(), &httpInterpretCallback, (void*)this, nullptr);
            if(err < 0) {
                netMessageAbortConnection(msg);
                return;
            } else {
                netMessagePost(res);    
            }

        } else {
            std::string path = http_root_dir_path + url;
            if(access(path.c_str(), F_OK) == 0) {
                //get mime type based on extension
                const char *mime_type = get_file_mime_type(path.c_str());   
                if(mime_type == nullptr) {
                    //not supported
                    netMessageSetStatusCodeAndReasonString(res, 403, "Forbidden");
                    netMessagePost(res);    
                } else {
                    std::string ext = get_file_ext(path);
                    if(ext == "osp") {
                        //oasis server script file extension
                        int32_t err = httpInterpretServerPage(res, url.c_str(), path.c_str(), &httpInterpretCallback, (void*)this, nullptr);
                        if(err < 0) {
                            netMessageAbortConnection(msg);
                            return;
                        }
                    } else {
                        netMessageSendFile(res, path.c_str(), mime_type);
                    }
                }
            } else {
                netMessageSetStatusCodeAndReasonString(res, 400, "Bad Request");
                netMessagePost(res);    
            }
        }
    }

    virtual void onResponse(const NetMessageRef &msg) {

    }
};

class EchoWsEventDelegate : public WsEventDelegate
{
public:
    EchoWsEventDelegate() {}
    virtual ~EchoWsEventDelegate() {}

public: 
    virtual void onOpen(const WsEventRef &evt) {
        fprintf(stdout, "Echo: Open\n");
    }

    virtual void onMessage(const WsEventRef &evt)  {
        fprintf(stdout, "Echo: Message\n");

        if(wsEventMessageType(evt) == kWsMessageText) {
            std::vector<uint8_t> data;
            if(wsEventData(evt, data) > 0) {
                std::string str = "Echo: ";
                str += std::string(data.data(), data.data()+data.size());
                wsSendText(evt, str.c_str());
            }
        }
    }

    virtual void onError(const WsEventRef &evt) {
        fprintf(stdout, "Echo: Error\n");
    }

    virtual void onClose(const WsEventRef &evt) {
        fprintf(stdout, "Echo: Close\n");
    }
};


static bool continue_running = true;

void cancel_handler(int signum)
{
    continue_running = false;
}


void printUsage(const char *pgname)
{
    fprintf(stderr, "USAGE: %s [-p <port number>] [-s] <documnet root dir>\n", pgname);
}

using namespace oasis;

int main(int argc, char* argv[])
{
    int32_t err;
    int c;
    int32_t http_port = 80;
    bool is_secure = false;

    std::shared_ptr<MyHttpUpStreamDelegate> http_delegate;
    HttpServerRef http_server;

    opterr = 0;
    while ((c = getopt(argc, argv, "p:sh")) != -1) {
        switch (c) {
        case 'p':
            if(optarg == nullptr) {
                fprintf(stderr, "error: bad option argument '%c'\n", optopt);
                return -1;
            }
            http_port = atoi(optarg);
            if(http_port <= 0 || http_port > 65535) {
                fprintf(stderr, "bad port number: %d\n", http_port);
                return -1;
            }
            break;
        case 's':
            is_secure = true;
            break;
        case 'h':
        default:
            printUsage(argv[0]);
            return -1;
        }
    }

    if(argc-optind < 1) {
        fprintf(stderr, "error: invalid or insufficient arguments (%d, %d)\n", argc, optind);
        printUsage(argv[0]);
        return -1;
    }

    http_root_dir_path = argv[optind];
    if(!isDirectory(http_root_dir_path.c_str())) {
        fprintf(stderr, "error: invalid root directory: %s\n", http_root_dir_path.c_str());
        printUsage(argv[0]);
        return -1;
    }

    key_value_map_t parameters;

    parameters["offs-disable"] = "1";
    if(oasis::initialize(parameters) < 0) {
        fprintf(stderr,  "Oasis init failed\n");
        return -1;
    }

    parameters.clear();

    parameters["port"] = std::to_string(http_port);
    parameters["root-dir"] = http_root_dir_path.c_str();
    parameters["content-length-max"] = std::to_string(3*1024*1024);

    parameters["tls-disable-certificate-validation"] = "1";

    if(is_secure) {
        parameters["tls-enabled"] = "1";
        parameters["tls-version"] = "1.2";

        parameters["cert-file-path"] = "/mnt/sd/webserver-cert.pem";
        parameters["pkey-file-path"] = "/mnt/sd/webserver-key.pem";
    }

    http_delegate = std::make_shared<MyHttpUpStreamDelegate>();

    http_server = oasis::createHttpServer(parameters, http_delegate);
    if (http_server) {
        err = oasis::startHttpServer(http_server);
        ASSERT(err == 0);
        if(err < 0) {
            fprintf(stderr,  "HTTPS server failed\n");
            goto done;
        }
        fprintf(stdout, "HTTP%s running at %d...\n", is_secure?"S":"", http_port);

        //serverless websocket handler
        parameters.clear();
        std::shared_ptr<EchoWsEventDelegate> echo_delegate = std::make_shared<EchoWsEventDelegate>();
        if(createHttpWsService(http_server, "/ws/echo", parameters, echo_delegate) >= 0) {
        }
    }

    do {
        usleep(100000);
    } while(continue_running);

done:
    if(http_server) {
        oasis::destroyHttpServer(http_server);
    }

    oasis::finalize();

    return 0;
}

클라이언트#

아래는 웹 사이트에 접속해서 홈페이지 HTML 문서를 다운받는 클라이언트는 예입니다.

#include "OasisAPI.h"
#include "OasisWeb.h"

#include "OasisLog.h"

#include <thread>
#include <mutex>
#include <memory>
#include <condition_variable>

#define DLOG_THIS   0x00080000

#undef DLOG_FLAGS
#define  DLOG_FLAGS (DLOG_FLAGS_DEFAULT|DLOG_THIS/**/)

#undef DLOG_TAG
#define DLOG_TAG "HTTPCLI"

using namespace oasis;

int main(int argc, char* argv[])
{
    int32_t err;

    int32_t status_code;
    std::string reason_string;
    std::string content_type; 
    std::vector<char> res_content;
    size_t content_length;

    const char *url = "https://google.com/";

    HttpConnectionRef conn;
    NetMessageRef msg, res_msg;
    int32_t wait_count = 0;

    key_value_map_t parameters, fields;


    parameters["offs-disable"] = "1";
    parameters["media-cache-size"] = "4096";
    if(oasis::initialize(parameters) < 0) {
        DLOG(DLOG_ERROR, "Oasis init failed\n");
        return -1;
    }

    parameters.clear();

    // 클라이언트의 인증서가 필요할 경우 설정합니다.
    // parameters["ca-certs-file-path"] = "/data/certs/cacerts.pem\x0a/data/certs/RootCA.pem";
    // parameters["cert-file-path"] = "/data/certs/client_fullchain.pem";
    // parameters["pkey-file-path"] = "/data/certs/client_privkey.pem";

    parameters["tls-disable-certificate-validation"] = "1";

    conn = httpOpenConnectionWithParameters(url, 30000, parameters);
    if(!conn) {
        DLOG(DLOG_THIS, "connection failed!\n");
        goto done;
    }

    msg = httpConnectionGetRequestMessage(conn);
    ASSERT(msg);
    if(!msg) {
        return -1;
    }

    netMessageSetMethod(msg, "GET");

    if(netMessagePost(msg) < 0) {
        DLOG(DLOG_ERROR, "post error\n");
        goto done;
    }

    wait_count = 0;
    do {
        res_msg = httpConnectionGetResponseMessage(conn, 1000);
        wait_count++;
    } while(res_msg == nullptr && wait_count*1000 < 30000); //30seconds

    if(res_msg == nullptr) {
        //either timeout or aborted
        DLOG(DLOG_ERROR, "res timeout\n");
        goto done;
    }


    status_code = netMessageGetStatusCodeAndReasonString(res_msg, reason_string);
    DLOG(DLOG_THIS, "Response: %d %s\n", status_code, reason_string.c_str());

    parameters.clear();
    netMessageUriGetQueryParameters(res_msg, parameters);
    if(parameters.empty() == false) {
        DLOG(DLOG_THIS, "Parameters:\n");
        for(auto p : parameters) {
            DLOG(DLOG_THIS, "    [%s] = %s\n", p.first.c_str(), p.second.c_str());
        }
    }

    DLOG(DLOG_THIS, "Headers:\n");
    fields.clear();
    netMessageGetHeaderFields(res_msg, fields);
    for(auto p : fields) {
        DLOG(DLOG_THIS, "    [%s] = %s\n", p.first.c_str(), p.second.c_str());
    }


    content_length = netMessageGetContentLength(res_msg);
    DLOG(DLOG_THIS, "Content length: %d\n", content_length);
    netMessageGetContentType(res_msg, content_type);
    DLOG(DLOG_THIS, "Content type: %s\n", content_type.c_str());

    netMessageGetContent(res_msg, res_content);
    //DUMP("REG_RES", res_content.data(), res_content.size());

    if(content_length > 0) {
        char path[PATH_MAX];
        sprintf(path, "/tmp/%u.html", (uint32_t)time(NULL));
        FILE *fp = fopen(path, "w");
        if(fp) {
            fwrite(res_content.data(), 1, res_content.size(), fp);
            fclose(fp);
            DLOG(DLOG_THIS, "saved to %s, %d bytes\n", path, content_length);
        }       
    }

    httpCloseConnection(conn);
    conn = nullptr;

done:

    oasis::finalize();

    return 0;
}