| Title: | HTTP(S) File Server with Range Requests and Unbounded CORS Using 'go' |
|---|---|
| Description: | Provides a lightweight HTTP(S) file server implemented in Go and exposed to R. It supports range requests, configurable CORS and COOP headers, and optional TLS. The package builds and runs a background server that can be cleanly shut down from R using an OS pipe and C/Go interop. Asynchronous log handling is also supported. |
| Authors: | Sounkou Mahamane Toure [aut, cre] |
| Maintainer: | Sounkou Mahamane Toure <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.1.3-0.9000 |
| Built: | 2026-10-16 10:18:03 UTC |
| Source: | https://github.com/sounkou-bioinfo/goServeR |
Create default console log handler
.create_default_log_handler(fd).create_default_log_handler(fd)
fd |
file descriptor for log pipe |
external pointer to log handler
Default log callback - writes to console
.default_log_callback(handler, message, user).default_log_callback(handler, message, user)
handler |
external pointer to handler |
message |
log message |
user |
user data (unused) |
Add an API key to the authentication system
addAuthKey(server_handle, key)addAuthKey(server_handle, key)
server_handle |
External pointer from runServer(blocking=FALSE, auth=TRUE) |
key |
Character string, the API key to add |
Invisible TRUE
Convert server list to data frame
## S3 method for class 'server_list' as.data.frame(x, ...)## S3 method for class 'server_list' as.data.frame(x, ...)
x |
a server_list object |
... |
additional arguments (ignored) |
a data.frame with server information
Remove all API keys from the authentication system
clearAuthKeys(server_handle)clearAuthKeys(server_handle)
server_handle |
External pointer from runServer(blocking=FALSE, auth=TRUE) |
Invisible TRUE
Create file log handler
createFileLogHandler(fd, logfile = tempfile("goserveR_", fileext = ".log"))createFileLogHandler(fd, logfile = tempfile("goserveR_", fileext = ".log"))
fd |
file descriptor for log pipe |
logfile |
path to log file |
external pointer to log handler
Create silent log handler (no-op)
createSilentLogHandler(fd)createSilentLogHandler(fd)
fd |
file descriptor for log pipe |
external pointer to log handler
Generates a self-signed X.509 certificate and private key as PEM using
nanonext::write_cert(), then writes them to temporary files accepted by
Go's HTTPS server. The private-key file is restricted to the current user on
platforms that support Unix-style file modes.
createTLSCertificate( cn = "127.0.0.1", valid = "20301231235959", directory = tempdir() )createTLSCertificate( cn = "127.0.0.1", valid = "20301231235959", directory = tempdir() )
cn |
Certificate common name, usually the server host name or IP address. |
valid |
Certificate expiry in |
directory |
Directory in which to create the temporary PEM files. |
A goserveR_tls_certificate object containing the in-memory
PEM values and the certfile and keyfile paths. Pass the
object directly to the tls argument of runServer().
isRunning Check if a background server is still running
isRunning(handle)isRunning(handle)
handle |
external pointer returned by runServer(blocking=FALSE) |
logical, TRUE if server is running, FALSE otherwise
## Not run: h <- runServer(dir = ".", addr = "127.0.0.1:8080", blocking = FALSE) isRunning(h) # TRUE shutdownServer(h) isRunning(h) # FALSE ## End(Not run)## Not run: h <- runServer(dir = ".", addr = "127.0.0.1:8080", blocking = FALSE) isRunning(h) # TRUE shutdownServer(h) isRunning(h) # FALSE ## End(Not run)
Get all current API keys in the authentication system
listAuthKeys(server_handle)listAuthKeys(server_handle)
server_handle |
External pointer from runServer(blocking=FALSE, auth=TRUE) |
Character vector of current API keys
listServers List all running background servers with detailed information
listServers()listServers()
a server_list S3 object containing server information
Print method for individual server_info objects
## S3 method for class 'server_info' print(x, index = NULL, ...)## S3 method for class 'server_info' print(x, index = NULL, ...)
x |
a server_info object |
index |
server index number for display |
... |
additional arguments (ignored) |
Print method for server_list objects
## S3 method for class 'server_list' print(x, ...)## S3 method for class 'server_list' print(x, ...)
x |
a server_list object |
... |
additional arguments (ignored) |
Register a log handler for a file descriptor
registerLogHandler(fd, callback, user = NULL)registerLogHandler(fd, callback, user = NULL)
fd |
file descriptor to monitor |
callback |
R function to call when data is available |
user |
user data passed to callback |
external pointer to log handler
Remove an API key from the authentication system
removeAuthKey(server_handle, key)removeAuthKey(server_handle, key)
server_handle |
External pointer from runServer(blocking=FALSE, auth=TRUE) |
key |
Character string, the API key to remove |
Invisible TRUE
Remove a log handler
removeLogHandler(handler)removeLogHandler(handler)
handler |
external pointer to log handler |
logical indicating success
Delete generated TLS credential files
removeTLSCertificate(credentials)removeTLSCertificate(credentials)
credentials |
An object returned by |
Invisibly, TRUE if neither credential file remains.
Run the go http server (blocking or background)
runServer( dir = getwd(), addr = "0.0.0.0:8181", prefix = "", blocking = TRUE, cors = FALSE, coop = FALSE, tls = FALSE, certfile = "cert.pem", keyfile = "key.pem", silent = FALSE, log_handler = NULL, auth_keys = c(), auth = FALSE, initial_keys = c(), mustWork = FALSE, ... )runServer( dir = getwd(), addr = "0.0.0.0:8181", prefix = "", blocking = TRUE, cors = FALSE, coop = FALSE, tls = FALSE, certfile = "cert.pem", keyfile = "key.pem", silent = FALSE, log_handler = NULL, auth_keys = c(), auth = FALSE, initial_keys = c(), mustWork = FALSE, ... )
dir |
character vector of directories to serve |
addr |
address |
prefix |
character vector of server prefixes (must have same length as dir) |
blocking |
logical, if FALSE runs in background and returns a handle |
cors |
logical, enable CORS headers |
coop |
logical, enable COOP/COEP headers |
tls |
Logical to enable TLS (HTTPS), or an object returned by
|
certfile |
path to TLS certificate file |
keyfile |
path to TLS key file |
silent |
logical, suppress server logs |
log_handler |
function, custom log handler function(handler, message, user) |
auth_keys |
character vector of API keys for authentication. Default c() = no auth |
auth |
logical, enable dynamic authentication system (non-blocking mode only) |
initial_keys |
character vector of initial API keys for dynamic auth system |
mustWork |
logical, if TRUE and non-blocking, will check if server actually started and throw error if it failed (default FALSE for backward compatibility) |
... |
additional arguments passed to the server |
NULL (if blocking) or an external pointer (if non-blocking)
## Not run: # Start a blocking server (will block the R session) # runServer(dir = ".", addr = "0.0.0.0:8080") # Start a background server (returns a handle) h <- runServer(dir = ".", addr = "0.0.0.0:8080", blocking = FALSE) # Start a server with static auth keys (backward compatible) h <- runServer( dir = ".", addr = "0.0.0.0:8080", blocking = FALSE, auth_keys = c("secret123", "token456") ) # Start a server with dynamic auth system h <- runServer( dir = ".", addr = "0.0.0.0:8080", blocking = FALSE, auth = TRUE, initial_keys = c("secret123") ) # Manage auth keys dynamically (only with auth=TRUE) auth <- attr(h, "auth") addAuthKey(auth, "new_key_456") removeAuthKey(auth, "secret123") listAuthKeys(auth) # Start a server serving multiple directories h <- runServer( dir = c("./data", "./docs", "."), prefix = c("/api/data", "/docs", "/files"), addr = "0.0.0.0:8080", blocking = FALSE ) # Start a server with custom log handler logfile <- tempfile("server_", fileext = ".log") h <- runServer( dir = ".", addr = "0.0.0.0:8080", blocking = FALSE, log_handler = function(handler, message, user) { cat("[CUSTOM]", message, file = logfile, append = TRUE) } ) # List all running background servers listServers() # Get a summary view summary(listServers()) # Shutdown a background server shutdownServer(h) ## End(Not run)## Not run: # Start a blocking server (will block the R session) # runServer(dir = ".", addr = "0.0.0.0:8080") # Start a background server (returns a handle) h <- runServer(dir = ".", addr = "0.0.0.0:8080", blocking = FALSE) # Start a server with static auth keys (backward compatible) h <- runServer( dir = ".", addr = "0.0.0.0:8080", blocking = FALSE, auth_keys = c("secret123", "token456") ) # Start a server with dynamic auth system h <- runServer( dir = ".", addr = "0.0.0.0:8080", blocking = FALSE, auth = TRUE, initial_keys = c("secret123") ) # Manage auth keys dynamically (only with auth=TRUE) auth <- attr(h, "auth") addAuthKey(auth, "new_key_456") removeAuthKey(auth, "secret123") listAuthKeys(auth) # Start a server serving multiple directories h <- runServer( dir = c("./data", "./docs", "."), prefix = c("/api/data", "/docs", "/files"), addr = "0.0.0.0:8080", blocking = FALSE ) # Start a server with custom log handler logfile <- tempfile("server_", fileext = ".log") h <- runServer( dir = ".", addr = "0.0.0.0:8080", blocking = FALSE, log_handler = function(handler, message, user) { cat("[CUSTOM]", message, file = logfile, append = TRUE) } ) # List all running background servers listServers() # Get a summary view summary(listServers()) # Shutdown a background server shutdownServer(h) ## End(Not run)
shutdownServer Shutdown a background server
shutdownServer(handle)shutdownServer(handle)
handle |
external pointer returned by runServer(blocking=FALSE) |
StartServer (advanced/manual use) Start a server (C-level, advanced)
StartServer( dir, addr, prefix, blocking, cors = FALSE, coop = FALSE, tls = FALSE, certfile = "cert.pem", keyfile = "key.pem", silent = FALSE, log_handler = NULL, auth_keys = c() )StartServer( dir, addr, prefix, blocking, cors = FALSE, coop = FALSE, tls = FALSE, certfile = "cert.pem", keyfile = "key.pem", silent = FALSE, log_handler = NULL, auth_keys = c() )
dir |
character vector of directories to serve |
addr |
address |
prefix |
character vector of server prefixes (must have same length as dir) |
blocking |
logical, if FALSE runs in background and returns a handle |
cors |
logical, enable CORS headers |
coop |
logical, enable COOP/COEP headers |
tls |
logical, enable TLS (HTTPS) |
certfile |
path to TLS certificate file |
keyfile |
path to TLS key file |
silent |
logical, suppress server logs |
log_handler |
function, custom log handler function(handler, message, user) |
auth_keys |
character vector of API keys for authentication |
Summary method for server_list objects
## S3 method for class 'server_list' summary(object, ...)## S3 method for class 'server_list' summary(object, ...)
object |
a server_list object |
... |
additional arguments (ignored) |
Replaces an existing API key while keeping the replacement valid throughout the operation by adding the new key before removing the old key.
updateAuthKey(server_handle, old_key, new_key)updateAuthKey(server_handle, old_key, new_key)
server_handle |
External pointer from
|
old_key |
Existing API key. |
new_key |
Replacement API key. |
Invisible TRUE.