Files
wren/manual_src/pages/api/tls.html
T
retoor 04e467e09b feat: add wasm build targets, profile hooks, os_demo example, and restructure manual source
- Add `wasm`, `wasm-clean`, and `install-emscripten` phony targets to Makefile for WebAssembly cross-compilation
- Insert `WREN_PROFILE_ENTER`/`WREN_PROFILE_EXIT` macros in `wren_vm.h` and `wren_vm.c` to support optional runtime profiling via `WREN_PROFILE_ENABLED`
- Create `example/os_demo.wren` demonstrating Platform, Process, and conditional exit usage
- Update `example/regex_demo.wren` to import `Match` and exercise Match object properties, groups, and `matchAll`
- Remove static HTML manual pages (`base64.html`, `dns.html`, `json.html`) and replace with structured `manual_src/` directory containing Jinja2 templates, YAML metadata, and content pages
- Expand `README.md` with build targets table, manual building instructions, source layout, and guide for adding new module documentation
2026-01-26 04:12:14 +00:00

154 lines
6.1 KiB
HTML

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}
{% set page_title = "tls" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "tls"}] %}
{% set prev_page = {"url": "api/timer.html", "title": "timer"} %}
{% set next_page = {"url": "api/udp.html", "title": "udp"} %}
{% block article %}
<h1>tls</h1>
<p>The <code>tls</code> module provides SSL/TLS socket support for secure network connections. It uses OpenSSL for encryption and is used internally by the <code>http</code> module for HTTPS connections.</p>
<pre><code>import "tls" for TlsSocket</code></pre>
<div class="toc">
<h4>On This Page</h4>
<ul>
<li><a href="#tlssocket-class">TlsSocket Class</a></li>
<li><a href="#examples">Examples</a></li>
</ul>
</div>
<h2 id="tlssocket-class">TlsSocket Class</h2>
<div class="class-header">
<h3>TlsSocket</h3>
<p>SSL/TLS encrypted socket connection</p>
</div>
<h3>Static Methods</h3>
<div class="method-signature">
<span class="method-name">TlsSocket.connect</span>(<span class="param">host</span>, <span class="param">port</span>, <span class="param">hostname</span>) &#8594; <span class="type">TlsSocket</span>
</div>
<p>Establishes a TLS connection to a remote server.</p>
<ul class="param-list">
<li><span class="param-name">host</span> <span class="param-type">(String)</span> - IP address to connect to</li>
<li><span class="param-name">port</span> <span class="param-type">(Num)</span> - Port number (typically 443 for HTTPS)</li>
<li><span class="param-name">hostname</span> <span class="param-type">(String)</span> - Server hostname for SNI (Server Name Indication)</li>
<li><span class="returns">Returns:</span> Connected TlsSocket instance</li>
</ul>
<pre><code>var socket = TlsSocket.connect("93.184.216.34", 443, "example.com")</code></pre>
<h3>Methods</h3>
<div class="method-signature">
<span class="method-name">write</span>(<span class="param">text</span>)
</div>
<p>Writes data to the TLS connection. This is an async operation that blocks until the data is sent.</p>
<ul class="param-list">
<li><span class="param-name">text</span> <span class="param-type">(String)</span> - Data to send</li>
</ul>
<pre><code>socket.write("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n")</code></pre>
<div class="method-signature">
<span class="method-name">read</span>() &#8594; <span class="type">String|null</span>
</div>
<p>Reads data from the TLS connection. Blocks until data is available. Returns null when the connection is closed.</p>
<ul class="param-list">
<li><span class="returns">Returns:</span> Data received as a string, or null if connection closed</li>
</ul>
<pre><code>var data = socket.read()
if (data != null) {
System.print(data)
}</code></pre>
<div class="method-signature">
<span class="method-name">close</span>()
</div>
<p>Closes the TLS connection and releases resources.</p>
<pre><code>socket.close()</code></pre>
<h2 id="examples">Examples</h2>
<h3>Basic HTTPS Request</h3>
<pre><code>import "tls" for TlsSocket
import "dns" for Dns
var host = "example.com"
var ip = Dns.lookup(host)
var socket = TlsSocket.connect(ip, 443, host)
socket.write("GET / HTTP/1.1\r\n")
socket.write("Host: %(host)\r\n")
socket.write("Connection: close\r\n")
socket.write("\r\n")
var response = ""
while (true) {
var chunk = socket.read()
if (chunk == null) break
response = response + chunk
}
socket.close()
System.print(response)</code></pre>
<h3>Reading Until Complete</h3>
<pre><code>import "tls" for TlsSocket
import "dns" for Dns
var host = "api.example.com"
var ip = Dns.lookup(host)
var socket = TlsSocket.connect(ip, 443, host)
socket.write("GET /data HTTP/1.1\r\n")
socket.write("Host: %(host)\r\n")
socket.write("Accept: application/json\r\n")
socket.write("Connection: close\r\n\r\n")
var buffer = ""
while (true) {
var data = socket.read()
if (data == null) break
buffer = buffer + data
}
socket.close()
var bodyStart = buffer.indexOf("\r\n\r\n")
if (bodyStart != -1) {
var body = buffer[bodyStart + 4..-1]
System.print("Response body: %(body)")
}</code></pre>
<h3>Using with DNS Resolution</h3>
<pre><code>import "tls" for TlsSocket
import "dns" for Dns
var hostname = "secure.example.com"
var ip = Dns.lookup(hostname, 4)
System.print("Connecting to %(ip)")
var socket = TlsSocket.connect(ip, 443, hostname)
socket.write("GET /secure-endpoint HTTP/1.1\r\nHost: %(hostname)\r\n\r\n")
var response = socket.read()
System.print(response)
socket.close()</code></pre>
<div class="admonition note">
<div class="admonition-title">Note</div>
<p>The <code>hostname</code> parameter is used for SNI (Server Name Indication), which is required when connecting to servers that host multiple domains on the same IP address. It should match the domain name in the server's certificate.</p>
</div>
<div class="admonition tip">
<div class="admonition-title">Tip</div>
<p>For most use cases, consider using the higher-level <code>http</code> module which handles TLS connections, HTTP protocol details, and response parsing automatically.</p>
</div>
{% endblock %}