From 41c632c13f0463a3644375d26b66b20e8030c3fb Mon Sep 17 00:00:00 2001 From: decke Date: Wed, 25 Mar 2026 20:40:37 -0700 Subject: [PATCH] Some additional clarifications on responsible use --- AGENTS.md | 2 +- README.md | 8 +++++--- toolbox/+mhs/+internal/GoSidecarTransport.m | 2 +- toolbox/doc/deployment.md | 14 +++++++++++--- 4 files changed, 18 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6e6bc32..c0eaafa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ This file provides guidance for AI coding agents working on this codebase. Read ## What This Project Is -`matlab-http-server` is a zero-dependency HTTP server framework for MATLAB. It is intended to support both REST APIs and static file serving in base MATLAB, with an optional Go sidecar transport for server-oriented deployments. +`matlab-http-server` is a zero-dependency HTTP server framework for MATLAB. It is intended to support both REST APIs and static file serving in base MATLAB, with an optional Go sidecar transport for automated or long-running MATLAB workflows. Developers define endpoints by subclassing `mhs.ApiController`, implementing the abstract `registerRoutes` method, and writing handler methods with the signature `res = myHandler(obj, req, res)`. diff --git a/README.md b/README.md index 5bde412..9c6e334 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ curl http://localhost:8080/api/echo -d '{"msg":"hi"}' -H "Content-Type: applicat curl http://localhost:8080/api/echo -d "{\"msg\":\"hi\"}" -H "Content-Type: application/json" ``` -No config files, no external dependencies for core functionality, and no MATLAB Production Server license. +No config files, no external dependencies for core functionality, and no additional MATLAB products required by the framework itself beyond an appropriate MATLAB license. --- @@ -110,7 +110,7 @@ addpath(fullfile(pwd, 'matlab-http-server', 'toolbox')) ## Transport Selection -`matlab-http-server` is designed around transport abstraction. The default path should work in base MATLAB, while the Go sidecar remains available as an explicit opt-in for server-oriented deployments. +`matlab-http-server` is designed around transport abstraction. The default path should work in base MATLAB, while the Go sidecar remains available as an explicit opt-in for automated or long-running MATLAB workflows. ```matlab % Default transport @@ -266,7 +266,9 @@ Caddy (TLS, :443) -> matlab-http-server (:8080, localhost only) ### Licensing Note -Single-user local use and shared multi-user deployments may have different MathWorks licensing requirements. If you plan to host a team-facing web app or API on a shared machine, verify that your organization's MATLAB license permits that deployment model and has sufficient named users or concurrent seats, as applicable. +This project is intended to operate within the scope of an existing MATLAB license and does not extend MATLAB access beyond licensed users. + +Single-user local use and shared team deployments may have different MathWorks licensing requirements. If you plan to host a MATLAB-backed internal tool on a shared machine, verify that your organization's MATLAB license permits that deployment model and has sufficient named users or concurrent seats, as applicable. See the official MathWorks licensing documentation for details: diff --git a/toolbox/+mhs/+internal/GoSidecarTransport.m b/toolbox/+mhs/+internal/GoSidecarTransport.m index 30b3d8e..5380755 100644 --- a/toolbox/+mhs/+internal/GoSidecarTransport.m +++ b/toolbox/+mhs/+internal/GoSidecarTransport.m @@ -3,7 +3,7 @@ % Works with base MATLAB — no toolboxes required. % Go binary handles all HTTP; MATLAB handles request processing. % Communication over stdin/stdout using line-delimited JSON. -% Preferred for headless, server, and production deployments. +% Optional transport for automated or long-running MATLAB workflows. % % The binary must exist at toolbox/bin//matlab-http-bridge[.exe]. % Build from source: cd sidecar && make build-all diff --git a/toolbox/doc/deployment.md b/toolbox/doc/deployment.md index be06c66..dde4567 100644 --- a/toolbox/doc/deployment.md +++ b/toolbox/doc/deployment.md @@ -44,15 +44,17 @@ This keeps the frontend and API on the same origin and avoids extra CORS complex Uses `java.net.ServerSocket` coordinated by a MATLAB timer loop. Works in **Base MATLAB**. - **Pros**: Zero toolbox dependencies, straightforward local use, good default for desktop tools and demos. -- **Cons**: Less scalable than the Go sidecar for heavier request loads. +- **Cons**: Still subject to MATLAB's single-threaded handler model. ### 2. Go Sidecar Spawns an external Go binary to handle the HTTP socket layer and communicates with MATLAB over standard I/O. -- **Pros**: Better fit for headless or more server-oriented use cases, still works with Base MATLAB. +- **Pros**: Optional transport for improved I/O handling in automated or long-running MATLAB workflows, still works with Base MATLAB. - **Cons**: Requires the bundled `matlab-http-bridge` binary. +The Go transport does not change MATLAB's execution model or licensing requirements and should be used within the same constraints as the default transport. + ```matlab server = MatlabHttpServer(8080, Transport="go"); ``` @@ -61,12 +63,14 @@ server = MatlabHttpServer(8080, Transport="go"); ## Centralized - Small Team -To share a MATLAB API or internal tool with a small team, run it on a shared machine and put a reverse proxy such as Caddy or Nginx in front of it. +To make a MATLAB-backed internal tool available within a small team environment, run it on a shared machine and put a reverse proxy such as Caddy or Nginx in front of it. ### Licensing Considerations Shared deployments can have different MathWorks licensing requirements than a single-user local workflow. If multiple users will access the same MATLAB-backed web application or API, confirm that your organization's MATLAB license allows that deployment pattern and has enough named users or concurrent seats for the expected usage. +Access to MATLAB functionality through this server should be limited to users who are appropriately licensed, and deployments should not be used to provide MATLAB capabilities to unlicensed users. + This project does not change or extend MathWorks licensing terms. Treat the official MathWorks documentation as the source of truth for what your organization is permitted to run. - [Individual License Administration](https://www.mathworks.com/help/install/license/individual-license-administration.html) @@ -74,8 +78,12 @@ This project does not change or extend MathWorks licensing terms. Treat the offi - [Concurrent License Administration](https://www.mathworks.com/help/install/license/concurrent-licenses.html) - [Network Named User License Administration](https://www.mathworks.com/help/install/license/key-administrative-tasks.html) +This setup is intended for lightweight internal use cases and is not a substitute for MATLAB Production Server in production or high-concurrency environments. + ### Why Use a Reverse Proxy? +For internal or controlled network environments, a reverse proxy can be used to manage access and routing. + - **Security**: Dedicated web servers are better suited for external network exposure. - **TLS/SSL**: `matlab-http-server` does not provide HTTPS directly. - **Routing**: A proxy can route `/api/` to MATLAB and handle other paths differently if needed.