nv-easy-fetch

nv-easy-fetch
=======================
- a simple fetch server/client for beginner
- can directly send/recv any-javascript-value: excpet function-like | weak-like | stream-like
- you MUST use the server/client together, it NOT compatible with other server/client

install
=======
- npm install nv-easy-fetch

splitted
--------

usage
=====

const {
usage,
bw_client,
nd_client,
creat_srv_using_nodejs,
creat_srv_using_uwebsocket
} = require("nv-easy-fetch");

example
-------

$3

// npm install nv-jsval-fetch-bw
//copy /paste the DIST/dist of nv-jsval-fetch-bw to your browser

const jsval_fetch_from_url = async(url) => {
if(window.jsval_fetch) {
} else {
let code = await (await fetch(url)).text();
let script = document.createElement("script");
script.innerText = code;
document.head.appendChild(script);
}
return(window.jsval_fetch)
}

const {get,post} = await jsval_fetch_from_url("http://192.168.1.103:7777/");

await get("http://192.168.1.103:7777/", headers={},extra={})
await post("http://192.168.1.103:7777/", new Map([[123,new Set()],[undefined,NaN]]), headers={},extra={})

$3

const {get,post} = nd_client;
var r = await post("../___usock___#", new Map([[1,2],[3,4]]), headers={},tls_options={rejectUnauthorized:false})
// 【when using unix_sock , need end/split with "#" such as "x/y#" "x/y#/a/b/c/d...." 】
var r = await post("http://127.0.0.1:7777/",new Map([[1,2],[3,4]]), headers={},tls_options={rejectUnauthorized:false})
var r = await post("https://127.0.0.1:7443/",[new Date, 12345678901234567890n,new Set()],headers={},tls_options={rejectUnauthorized:false});

$3

const creat_srv = creat_srv_using_nodejs;

//for example: we reply a complicate jsvalue:
var TST_DATA_FOR_REPLY = [
{circular:null},
undefined,null,true,false,
"str",1.1,123456789n,new Date,/a-z/g,
new Set([1,2,3,4,5,6]),
new Map([[11,22],[33,44]]),
new Uint8Array([1,2,3,4]),
new ArrayBuffer(10),
new DataView(new ArrayBuffer(8, { maxByteLength: 16 })),
new Error("1",{cause:"xxx"}),new AggregateError([new Error(),new Error()]),
];
TST_DATA_FOR_REPLY[0].circular = TST_DATA_FOR_REPLY;

//write your server handle:
var ahandle = async (recved_data, recved_headers, from_client) => {
console.log({recved_data, recved_headers,from_client});
if(recved_data instanceof Map) {
return(TST_DATA_FOR_REPLY);
} else {
throw(new Error("must-be-map"))
}
};

// we create 4 server:

var srv_using_usock = await creat_srv("../___usock___",ahandle);
var srv_using_http = await creat_srv("http://127.0.0.1:7777/",ahandle);
var srv_using_unsafe_https = await creat_srv("https://127.0.0.1:7443/",ahandle);
var srv_using_https = await creat_srv(
https://127.0.0.1:7443/?
rejectUnauthorized &
key = test/fixtures/keys/agent2-key.pem &
cert = test/fixtures/keys/agent2-cert.pem
,
ahandle
);

// from client:

var r = await post("http://127.0.0.1:7777/",new Map([[1,2],[3,4]]))

/*
//on client:
[
{ circular: [Circular *1] },
undefined,
null,
true,
false,
'str',
1.1,
123456789n,
2024-01-16T11:31:02.867Z,
/a-z/g,
Set(6) { 1, 2, 3, 4, 5, 6 },
Map(2) { 11 => 22, 33 => 44 },
Uint8Array(4) [ 1, 2, 3, 4 ],
ArrayBuffer {
[Uint8Contents]: <00 00 00 00 00 00 00 00 00 00>,
byteLength: 10
},
DataView {
byteLength: 8,
byteOffset: 0,
buffer: ArrayBuffer {
[Uint8Contents]: <00 00 00 00 00 00 00 00>,
byteLength: 8
}
},
Error: 1
at REPL17:10:9
at Script.runInThisContext (node:vm:122:12)
at REPLServer.defaultEval (node:repl:570:29)
at bound (node:domain:433:15)
at REPLServer.runBound [as eval] (node:domain:444:12)
at REPLServer.onLine (node:repl:900:10)
at REPLServer.emit (node:events:523:35)
at REPLServer.emit (node:domain:489:12)
at [_onLine] [as _onLine] (node:internal/readline/interface:415:12)
at [_line] [as _line] (node:internal/readline/interface:886:18) {
[cause]: 'xxx'
},
AggregateError
at REPL17:10:38
at Script.runInThisContext (node:vm:122:12)
at REPLServer.defaultEval (node:repl:570:29)
at bound (node:domain:433:15)
at REPLServer.runBound [as eval] (node:domain:444:12)
at REPLServer.onLine (node:repl:900:10)
at REPLServer.emit (node:events:523:35)
at REPLServer.emit (node:domain:489:12)
at [_onLine] [as _onLine] (node:internal/readline/interface:415:12)
at [_line] [as _line] (node:internal/readline/interface:886:18)
]

//on server:
{
recved_data: Map(2) { 1 => 2, 3 => 4 },
recved_headers: {
'content-type': 'application/octet-stream',
'---dtype---': 'v8ser',
'---bytsz---': '13',
host: '127.0.0.1:7777',
connection: 'close',
'transfer-encoding': 'chunked'
},
from_client: {
address: '127.0.0.1',
family: 'IPv4',
port: 33724,
url: '/',
method: 'POST',
httpVersion: '1.1'
}
}
*/
var e = await post("http://127.0.0.1:7777/", 1234567890n)
console.log(e instanceof Error) //true

var r = await post("../___usock___#",new Map([[1,2],[3,4]]));
IF IS a unix_socket(path):
need end/split with a "#":
such as :
/xx/yy/ww/usock#/a/b/c/d
../usock#
var e = await post("../___usock___#", 1234567890n)
console.log(e instanceof Error) //true

$3

const creat_srv = creat_srv_using_uwebsocket;
//the api is a little from nodejs server
// refer to below

METHODS
========

APIS
=======

$3

usage.how_to_use_browser_client()

const jsval_fetch_from_url = async(url) => {
if(window.jsval_fetch) {
} else {
let code = await (await fetch(url)).text();
let script = document.createElement("script");
script.innerText = code;
document.head.appendChild(script);
}
return(window.jsval_fetch)
}

const {get,post} = await jsval_fetch_from_url();
await get(, headers={},extra={});
await post(,, headers={}, extra={});

$3

usage.how_to_use_nodejs_client()

//npm install nv-jsval-fetch-nd
const {get,post} = require("nv-jsval-fetch-nd");
await get (, headers={}, tls_options={rejectUnauthorized:false})
await post(,, headers={}, tls_options={rejectUnauthorized:false});

IF IS a unix_socket(path):
need end/split with a "#":
such as :
/xx/yy/ww/usock#/a/b/c/d
../usock#

$3

usage.how_to_use_srv_with_nodejs_builtin()

//npm install nv-jsval-fetch-srv-api-if-using-nodejs-builtin

String@is_file_path 【will be treated as using unix_socket】;

String@is_srv_launch_url::EXAMPLES :
IF USING HTTP:
http://: #OR
http:// #OR
http://:
IF USING HTTPS:
IF USING UNSAFE HTTPS: 【NONEED provide key AND cert】
https://: #OR
https:// #OR
https://:
IF USING SAFE HTTPS: 【MUST provide key AND cert】
https://:/ ?rejectUnauthorized & key= &cert= #OR
https:/// ?rejectUnauthorized & key= &cert= #OR
https://:/?rejectUnauthorized & key= &cert=
;

JsValhandle : async(
received_data : @any_jsval_except,
received_headers : Dict>,
client : Dict> 【url,method,httpVersion,family,address,port,addr_bfr_ngx_fwd】
)=> {

IF return(reply_data: @any_jsval_except) THEN will send reply_data to client
IF throw(reply_error: Error) THEN will send reply_error to client

},



creat_srv(
listen_on : String@is_file_path | String@is_srv_launch_url,
jsval_handle : JsValhandle, 【jsval handle】
other_handle : async(res,req)=>{}, 【
//normal handle
//the default normal handle,will reply a jsval_fetch.js javascript for browser
res.writeHead(200,'OK',{'Content-Type': 'application/javascript'});
res.end(BWAPI_CODE);
】
chown_to_user : String|undefined 【
this argument ONLY make sense IF the is a unix_socket:
IF you NOT use nginx:
just let it be undefined,
ELSE
its a uname such as "www-data"
】,
key_buf : ArrayBuffer | Buffer | Array | undefined 【
IF this is NOT undefined:
the extract-from will be ignored AND
will using this as ssl-key
】,
cert_buf : ArrayBuffer | Buffer | Array | undefined 【
IF this is NOT undefined:
the extract-from will be ignored AND
will using this as ssl-cert
】,
) -> Promise

$3

``typescript
//npm install nv-jsval-fetch-srv-api-if-using-uwebsocket

String@is_file_path 【will be treated as using unix_socket】;

String@is_srv_launch_url::EXAMPLES :
IF USING HTTP:
http://: #OR
http:// #OR
http://:
IF USING HTTPS:
IF USING UNSAFE HTTPS: 【NONEED provide key AND cert】
https://: #OR
https:// #OR
https://:
IF USING SAFE HTTPS: 【MUST provide key AND cert】
https://:/ ?rejectUnauthorized & key= &cert= #OR
https:/// ?rejectUnauthorized & key= &cert= #OR
https://:/?rejectUnauthorized & key= &cert=
;

JsValhandle : async(
received_data : @any_jsval_except,
received_headers : Dict>,
client : Dict> 【url,method,httpVersion,family,address,port,addr_bfr_ngx_fwd】
)=> {

IF return(reply_data: @any_jsval_except) THEN will send reply_data to client
IF throw(reply_error: Error) THEN will send reply_error to client

};

OtherHandleForUwebsocket : async(url, mthd, reqd:Dict, res:)=> {
//its different with nodejs,
//the res is res of uWebsocket refer to its documents
//the default normal handle,will reply a jsval_fetch.js javascript for browser
res.writeStatus('200 OK');
res.writeHeader('Content-Type','application/javascript');
res.end(BWAPI_CODE);
};


creat_srv(
listen_on : String@is_file_path | String@is_srv_launch_url,
jsval_handle : JsValhandle, 【jsval handle】
other_handle : OtherHandleForUwebsocket, 【uwebsocket original handle】
chown_to_user : String|undefined 【
this argument ONLY make sense IF the is a unix_socket:
IF you NOT use nginx:
just let it be undefined,
ELSE
its a uname such as "www-data"
】,
) -> Promise
``

LICENSE
=======
- ISC