├── .all-contributorsrc
├── .github
├── CODEOWNERS
├── FUNDING.yml
└── ISSUE_TEMPLATE
│ ├── bug_report.md
│ └── feature_request.md
├── .gitignore
├── .vscode
└── settings.json
├── CODE_OF_CONDUCT.md
├── LICENSE
├── README.md
├── docs
├── hello-sse
│ ├── api.go
│ ├── api.wasm
│ ├── index.html
│ └── sw.js
├── hello-state-keepalive
│ ├── index.html
│ └── sw.js
├── hello-state
│ ├── api.go
│ ├── api.wasm
│ ├── index.html
│ └── sw.js
├── hello
│ ├── api.go
│ ├── api.wasm
│ ├── index.html
│ └── sw.js
├── index.html
└── tinygo
│ ├── README.md
│ ├── api.wasm
│ ├── handlers.go
│ ├── index.html
│ ├── server.go
│ ├── sw.js
│ └── wasm.go
├── example_json_test.go
├── go.mod
├── go.sum
├── internal
├── jstype
│ └── types.go
├── readablestream
│ ├── reader.go
│ └── writer.go
└── safejs
│ ├── bytes.go
│ ├── func.go
│ └── value.go
├── package-lock.json
├── package.go
├── package.json
├── request.go
├── response.go
├── serve.go
└── sw.js
/.all-contributorsrc:
--------------------------------------------------------------------------------
1 | {
2 | "projectName": "go-wasm-http-server",
3 | "projectOwner": "nlepage",
4 | "repoType": "github",
5 | "repoHost": "https://github.com",
6 | "files": [
7 | "README.md"
8 | ],
9 | "imageSize": 100,
10 | "commit": false,
11 | "commitConvention": "gitmoji",
12 | "contributors": [
13 | {
14 | "login": "jphastings",
15 | "name": "JP Hastings-Edrei",
16 | "avatar_url": "https://avatars.githubusercontent.com/u/42999?v=4",
17 | "profile": "https://byjp.me/",
18 | "contributions": [
19 | "code",
20 | "doc",
21 | "example"
22 | ]
23 | },
24 | {
25 | "login": "EliCDavis",
26 | "name": "Eli Davis",
27 | "avatar_url": "https://avatars.githubusercontent.com/u/9094977?v=4",
28 | "profile": "https://recolude.com/",
29 | "contributions": [
30 | "code",
31 | "bug"
32 | ]
33 | }
34 | ],
35 | "contributorsPerLine": 7,
36 | "linkToUsage": false
37 | }
38 |
--------------------------------------------------------------------------------
/.github/CODEOWNERS:
--------------------------------------------------------------------------------
1 | * @nlepage
--------------------------------------------------------------------------------
/.github/FUNDING.yml:
--------------------------------------------------------------------------------
1 | github: [nlepage]
2 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/bug_report.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Bug report
3 | about: Create a report to help us improve go-wasm-http-server
4 | title: ''
5 | labels: bug
6 | assignees: ''
7 |
8 | ---
9 |
10 | **Describe the bug**
11 | A clear and concise description of what the bug is.
12 |
13 | **To Reproduce**
14 | Steps to reproduce the behavior or a link to an example repository.
15 |
16 | **Expected behavior**
17 | A clear and concise description of what you expected to happen.
18 |
19 | **Environment (please complete the following information):**
20 | - OS: [e.g. linux, darwin]
21 | - Arch: [e.g. amd64, arm64]
22 | - Browser: [e.g. chrome 78, safari 13]
23 | - Go Version: [e.g. 1.13.3]
24 |
25 | **Additional context**
26 | Add any other context about the problem here.
27 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/feature_request.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Feature request
3 | about: Suggest an idea for go-wasm-http-server
4 | title: ''
5 | labels: enhancement
6 | assignees: ''
7 |
8 | ---
9 |
10 | **Is your feature request related to a problem? Please describe.**
11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
12 |
13 | **Describe the solution you'd like**
14 | A clear and concise description of what you want to happen.
15 |
16 | **Additional context**
17 | Add any other context or screenshots about the feature request here.
18 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules/
2 | *.wasm
3 | !docs/**/*.wasm
4 |
--------------------------------------------------------------------------------
/.vscode/settings.json:
--------------------------------------------------------------------------------
1 | {
2 | "go.toolsEnvVars": {
3 | "GOOS": "js",
4 | "GOARCH": "wasm"
5 | }
6 | }
7 |
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Contributor Covenant Code of Conduct
2 |
3 | ## Our Pledge
4 |
5 | In the interest of fostering an open and welcoming environment, we as
6 | contributors and maintainers pledge to making participation in our project and
7 | our community a harassment-free experience for everyone, regardless of age, body
8 | size, disability, ethnicity, sex characteristics, gender identity and expression,
9 | level of experience, education, socio-economic status, nationality, personal
10 | appearance, race, religion, or sexual identity and orientation.
11 |
12 | ## Our Standards
13 |
14 | Examples of behavior that contributes to creating a positive environment
15 | include:
16 |
17 | * Using welcoming and inclusive language
18 | * Being respectful of differing viewpoints and experiences
19 | * Gracefully accepting constructive criticism
20 | * Focusing on what is best for the community
21 | * Showing empathy towards other community members
22 |
23 | Examples of unacceptable behavior by participants include:
24 |
25 | * The use of sexualized language or imagery and unwelcome sexual attention or
26 | advances
27 | * Trolling, insulting/derogatory comments, and personal or political attacks
28 | * Public or private harassment
29 | * Publishing others' private information, such as a physical or electronic
30 | address, without explicit permission
31 | * Other conduct which could reasonably be considered inappropriate in a
32 | professional setting
33 |
34 | ## Our Responsibilities
35 |
36 | Project maintainers are responsible for clarifying the standards of acceptable
37 | behavior and are expected to take appropriate and fair corrective action in
38 | response to any instances of unacceptable behavior.
39 |
40 | Project maintainers have the right and responsibility to remove, edit, or
41 | reject comments, commits, code, wiki edits, issues, and other contributions
42 | that are not aligned to this Code of Conduct, or to ban temporarily or
43 | permanently any contributor for other behaviors that they deem inappropriate,
44 | threatening, offensive, or harmful.
45 |
46 | ## Scope
47 |
48 | This Code of Conduct applies both within project spaces and in public spaces
49 | when an individual is representing the project or its community. Examples of
50 | representing a project or community include using an official project e-mail
51 | address, posting via an official social media account, or acting as an appointed
52 | representative at an online or offline event. Representation of a project may be
53 | further defined and clarified by project maintainers.
54 |
55 | ## Enforcement
56 |
57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be
58 | reported by contacting the project team at nicolas.lepage+go-wasm-http-server@zenika.com. All
59 | complaints will be reviewed and investigated and will result in a response that
60 | is deemed necessary and appropriate to the circumstances. The project team is
61 | obligated to maintain confidentiality with regard to the reporter of an incident.
62 | Further details of specific enforcement policies may be posted separately.
63 |
64 | Project maintainers who do not follow or enforce the Code of Conduct in good
65 | faith may face temporary or permanent repercussions as determined by other
66 | members of the project's leadership.
67 |
68 | ## Attribution
69 |
70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
72 |
73 | [homepage]: https://www.contributor-covenant.org
74 |
75 | For answers to common questions about this code of conduct, see
76 | https://www.contributor-covenant.org/faq
77 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Apache License
2 | Version 2.0, January 2004
3 | http://www.apache.org/licenses/
4 |
5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6 |
7 | 1. Definitions.
8 |
9 | "License" shall mean the terms and conditions for use, reproduction,
10 | and distribution as defined by Sections 1 through 9 of this document.
11 |
12 | "Licensor" shall mean the copyright owner or entity authorized by
13 | the copyright owner that is granting the License.
14 |
15 | "Legal Entity" shall mean the union of the acting entity and all
16 | other entities that control, are controlled by, or are under common
17 | control with that entity. For the purposes of this definition,
18 | "control" means (i) the power, direct or indirect, to cause the
19 | direction or management of such entity, whether by contract or
20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
21 | outstanding shares, or (iii) beneficial ownership of such entity.
22 |
23 | "You" (or "Your") shall mean an individual or Legal Entity
24 | exercising permissions granted by this License.
25 |
26 | "Source" form shall mean the preferred form for making modifications,
27 | including but not limited to software source code, documentation
28 | source, and configuration files.
29 |
30 | "Object" form shall mean any form resulting from mechanical
31 | transformation or translation of a Source form, including but
32 | not limited to compiled object code, generated documentation,
33 | and conversions to other media types.
34 |
35 | "Work" shall mean the work of authorship, whether in Source or
36 | Object form, made available under the License, as indicated by a
37 | copyright notice that is included in or attached to the work
38 | (an example is provided in the Appendix below).
39 |
40 | "Derivative Works" shall mean any work, whether in Source or Object
41 | form, that is based on (or derived from) the Work and for which the
42 | editorial revisions, annotations, elaborations, or other modifications
43 | represent, as a whole, an original work of authorship. For the purposes
44 | of this License, Derivative Works shall not include works that remain
45 | separable from, or merely link (or bind by name) to the interfaces of,
46 | the Work and Derivative Works thereof.
47 |
48 | "Contribution" shall mean any work of authorship, including
49 | the original version of the Work and any modifications or additions
50 | to that Work or Derivative Works thereof, that is intentionally
51 | submitted to Licensor for inclusion in the Work by the copyright owner
52 | or by an individual or Legal Entity authorized to submit on behalf of
53 | the copyright owner. For the purposes of this definition, "submitted"
54 | means any form of electronic, verbal, or written communication sent
55 | to the Licensor or its representatives, including but not limited to
56 | communication on electronic mailing lists, source code control systems,
57 | and issue tracking systems that are managed by, or on behalf of, the
58 | Licensor for the purpose of discussing and improving the Work, but
59 | excluding communication that is conspicuously marked or otherwise
60 | designated in writing by the copyright owner as "Not a Contribution."
61 |
62 | "Contributor" shall mean Licensor and any individual or Legal Entity
63 | on behalf of whom a Contribution has been received by Licensor and
64 | subsequently incorporated within the Work.
65 |
66 | 2. Grant of Copyright License. Subject to the terms and conditions of
67 | this License, each Contributor hereby grants to You a perpetual,
68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69 | copyright license to reproduce, prepare Derivative Works of,
70 | publicly display, publicly perform, sublicense, and distribute the
71 | Work and such Derivative Works in Source or Object form.
72 |
73 | 3. Grant of Patent License. Subject to the terms and conditions of
74 | this License, each Contributor hereby grants to You a perpetual,
75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76 | (except as stated in this section) patent license to make, have made,
77 | use, offer to sell, sell, import, and otherwise transfer the Work,
78 | where such license applies only to those patent claims licensable
79 | by such Contributor that are necessarily infringed by their
80 | Contribution(s) alone or by combination of their Contribution(s)
81 | with the Work to which such Contribution(s) was submitted. If You
82 | institute patent litigation against any entity (including a
83 | cross-claim or counterclaim in a lawsuit) alleging that the Work
84 | or a Contribution incorporated within the Work constitutes direct
85 | or contributory patent infringement, then any patent licenses
86 | granted to You under this License for that Work shall terminate
87 | as of the date such litigation is filed.
88 |
89 | 4. Redistribution. You may reproduce and distribute copies of the
90 | Work or Derivative Works thereof in any medium, with or without
91 | modifications, and in Source or Object form, provided that You
92 | meet the following conditions:
93 |
94 | (a) You must give any other recipients of the Work or
95 | Derivative Works a copy of this License; and
96 |
97 | (b) You must cause any modified files to carry prominent notices
98 | stating that You changed the files; and
99 |
100 | (c) You must retain, in the Source form of any Derivative Works
101 | that You distribute, all copyright, patent, trademark, and
102 | attribution notices from the Source form of the Work,
103 | excluding those notices that do not pertain to any part of
104 | the Derivative Works; and
105 |
106 | (d) If the Work includes a "NOTICE" text file as part of its
107 | distribution, then any Derivative Works that You distribute must
108 | include a readable copy of the attribution notices contained
109 | within such NOTICE file, excluding those notices that do not
110 | pertain to any part of the Derivative Works, in at least one
111 | of the following places: within a NOTICE text file distributed
112 | as part of the Derivative Works; within the Source form or
113 | documentation, if provided along with the Derivative Works; or,
114 | within a display generated by the Derivative Works, if and
115 | wherever such third-party notices normally appear. The contents
116 | of the NOTICE file are for informational purposes only and
117 | do not modify the License. You may add Your own attribution
118 | notices within Derivative Works that You distribute, alongside
119 | or as an addendum to the NOTICE text from the Work, provided
120 | that such additional attribution notices cannot be construed
121 | as modifying the License.
122 |
123 | You may add Your own copyright statement to Your modifications and
124 | may provide additional or different license terms and conditions
125 | for use, reproduction, or distribution of Your modifications, or
126 | for any such Derivative Works as a whole, provided Your use,
127 | reproduction, and distribution of the Work otherwise complies with
128 | the conditions stated in this License.
129 |
130 | 5. Submission of Contributions. Unless You explicitly state otherwise,
131 | any Contribution intentionally submitted for inclusion in the Work
132 | by You to the Licensor shall be under the terms and conditions of
133 | this License, without any additional terms or conditions.
134 | Notwithstanding the above, nothing herein shall supersede or modify
135 | the terms of any separate license agreement you may have executed
136 | with Licensor regarding such Contributions.
137 |
138 | 6. Trademarks. This License does not grant permission to use the trade
139 | names, trademarks, service marks, or product names of the Licensor,
140 | except as required for reasonable and customary use in describing the
141 | origin of the Work and reproducing the content of the NOTICE file.
142 |
143 | 7. Disclaimer of Warranty. Unless required by applicable law or
144 | agreed to in writing, Licensor provides the Work (and each
145 | Contributor provides its Contributions) on an "AS IS" BASIS,
146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 | implied, including, without limitation, any warranties or conditions
148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 | PARTICULAR PURPOSE. You are solely responsible for determining the
150 | appropriateness of using or redistributing the Work and assume any
151 | risks associated with Your exercise of permissions under this License.
152 |
153 | 8. Limitation of Liability. In no event and under no legal theory,
154 | whether in tort (including negligence), contract, or otherwise,
155 | unless required by applicable law (such as deliberate and grossly
156 | negligent acts) or agreed to in writing, shall any Contributor be
157 | liable to You for damages, including any direct, indirect, special,
158 | incidental, or consequential damages of any character arising as a
159 | result of this License or out of the use or inability to use the
160 | Work (including but not limited to damages for loss of goodwill,
161 | work stoppage, computer failure or malfunction, or any and all
162 | other commercial damages or losses), even if such Contributor
163 | has been advised of the possibility of such damages.
164 |
165 | 9. Accepting Warranty or Additional Liability. While redistributing
166 | the Work or Derivative Works thereof, You may choose to offer,
167 | and charge a fee for, acceptance of support, warranty, indemnity,
168 | or other liability obligations and/or rights consistent with this
169 | License. However, in accepting such obligations, You may act only
170 | on Your own behalf and on Your sole responsibility, not on behalf
171 | of any other Contributor, and only if You agree to indemnify,
172 | defend, and hold each Contributor harmless for any liability
173 | incurred by, or claims asserted against, such Contributor by reason
174 | of your accepting any such warranty or additional liability.
175 |
176 | END OF TERMS AND CONDITIONS
177 |
178 | APPENDIX: How to apply the Apache License to your work.
179 |
180 | To apply the Apache License to your work, attach the following
181 | boilerplate notice, with the fields enclosed by brackets "[]"
182 | replaced with your own identifying information. (Don't include
183 | the brackets!) The text should be enclosed in the appropriate
184 | comment syntax for the file format. We also recommend that a
185 | file or class name and description of purpose be included on the
186 | same "printed page" as the copyright notice for easier
187 | identification within third-party archives.
188 |
189 | Copyright 2025 Nicolas Lepage
190 |
191 | Licensed under the Apache License, Version 2.0 (the "License");
192 | you may not use this file except in compliance with the License.
193 | You may obtain a copy of the License at
194 |
195 | http://www.apache.org/licenses/LICENSE-2.0
196 |
197 | Unless required by applicable law or agreed to in writing, software
198 | distributed under the License is distributed on an "AS IS" BASIS,
199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200 | See the License for the specific language governing permissions and
201 | limitations under the License.
202 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
10 |
11 | > Embed your Go HTTP handlers in a ServiceWorker (using [WebAssembly](https://mdn.io/WebAssembly/)) and emulate an HTTP server!
12 |
13 | ## Examples
14 |
15 | - [Hello example](https://nlepage.github.io/go-wasm-http-server/hello) ([sources](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/hello))
16 | - [Hello example with state](https://nlepage.github.io/go-wasm-http-server/hello-state) ([sources](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/hello-state))
17 | - [Hello example with state and keepalive](https://nlepage.github.io/go-wasm-http-server/hello-state-keepalive) ([sources](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/hello-state-keepalive))
18 | - [Hello example with Server Sent Events](https://nlepage.github.io/go-wasm-http-server/hello-sse/) ([sources](https://nlepage.github.io/go-wasm-http-server/hello-sse/))
19 | - [😺 Catption generator example](https://nlepage.github.io/catption/wasm) ([sources](https://github.com/nlepage/catption/tree/wasm))
20 | - [Random password generator web server](https://nlepage.github.io/random-password-please/) ([sources](https://github.com/nlepage/random-password-please) forked from [jbarham/random-password-please](https://github.com/jbarham/random-password-please))
21 | - [Server fallbacks, and compiling with TinyGo](https://nlepage.github.io/go-wasm-http-server/tinygo/) (runs locally; see [sources & readme](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/tinygo#readme) for how to run this example)
22 |
23 | ## How?
24 |
25 | Below is a talk given at the Go devroom of FOSDEM 2021 explaining how `go-wasm-http-server` works.
26 |
27 | > [!WARNING]
28 | > `go-wasm-http-server` has suffered major changes since this talk, be aware that it is not accurate anymore on several aspects.
29 | > Please refer to the documentation below for up to date usage of `go-wasm-http-server`.
30 |
31 | [](https://youtu.be/O2RB_8ircdE)
32 |
33 | The slides are available [here](https://nlepage.github.io/go-wasm-http-talk/).
34 |
35 | ## Why?
36 |
37 | `go-wasm-http-server` can help you put up a demonstration for a project without actually running a Go HTTP server.
38 |
39 | ## Requirements
40 |
41 | `go-wasm-http-server` requires you to build your Go application to WebAssembly, so you need to make sure your code is compatible:
42 | - no C bindings
43 | - no System dependencies such as file system or network (database server for example)
44 | - For smaller WASM blobs, your code may also benefit from being compatible with, and compiled by, [TinyGo](https://tinygo.org/docs/reference/lang-support/stdlib/). See the TinyGo specific details below.
45 |
46 | ## Usage
47 |
48 | ### Step 1: Build to `js/wasm`
49 |
50 | In your Go code, replace [`http.ListenAndServe()`](https://pkg.go.dev/net/http#ListenAndServe) (or [`net.Listen()`](https://pkg.go.dev/net#Listen) + [`http.Serve()`](https://pkg.go.dev/net/http#Serve)) by [wasmhttp.Serve()](https://pkg.go.dev/github.com/nlepage/go-wasm-http-server#Serve):
51 |
52 | 📄 `server.go`
53 | ```go
54 | //go:build !js && !wasm
55 |
56 | package main
57 |
58 | import (
59 | "net/http"
60 | )
61 |
62 | func main() {
63 | // Define handlers...
64 |
65 | http.ListenAndServe(":8080", nil)
66 | }
67 | ```
68 |
69 | becomes:
70 |
71 | 📄 `server_js_wasm.go`
72 | ```go
73 | //go:build js && wasm
74 |
75 | package main
76 |
77 | import (
78 | wasmhttp "github.com/nlepage/go-wasm-http-server/v2"
79 | )
80 |
81 | func main() {
82 | // Define handlers...
83 |
84 | wasmhttp.Serve(nil)
85 | }
86 | ```
87 |
88 | You may want to use build tags as shown above (or file name suffixes) in order to be able to build both to WebAssembly and other targets.
89 |
90 | Then build your WebAssembly binary:
91 |
92 | ```sh
93 | # To compile with Go
94 | GOOS=js GOARCH=wasm go build -o server.wasm .
95 |
96 | # To compile with TinyGo, if your code is compatible
97 | GOOS=js GOARCH=wasm tinygo build -o server.wasm .
98 | ```
99 |
100 | ### Step 2: Create ServiceWorker file
101 |
102 | First, check the version of Go/TinyGo you compiled your wasm with:
103 |
104 | ```sh
105 | $ go version
106 | go version go1.23.4 darwin/arm64
107 | # ^------^
108 |
109 | $ tinygo version
110 | tinygo version 0.35.0 darwin/arm64 (using go version go1.23.4 and LLVM version 18.1.2)
111 | # ^----^
112 | ```
113 |
114 | Create a ServiceWorker file with the following code:
115 |
116 | 📄 `sw.js`
117 | ```js
118 | // Note the 'go.1.23.4' below, that matches the version you just found:
119 | importScripts('https://cdn.jsdelivr.net/gh/golang/go@go1.23.4/misc/wasm/wasm_exec.js')
120 | // If you compiled with TinyGo then, similarly, use:
121 | importScripts('https://cdn.jsdelivr.net/gh/tinygo-org/tinygo@0.35.0/targets/wasm_exec.js')
122 |
123 | importScripts('https://cdn.jsdelivr.net/gh/nlepage/go-wasm-http-server@v2.2.1/sw.js')
124 |
125 | registerWasmHTTPListener('path/to/server.wasm')
126 | ```
127 |
128 | By default the server will deploy at the ServiceWorker's scope root, check [`registerWasmHTTPListener()`'s API](https://github.com/nlepage/go-wasm-http-server#registerwasmhttplistenerwasmurl-options) for more information.
129 |
130 | You may want to add these additional event listeners in your ServiceWorker:
131 |
132 | ```js
133 | // Skip installed stage and jump to activating stage
134 | addEventListener('install', (event) => {
135 | event.waitUntil(skipWaiting())
136 | })
137 |
138 | // Start controlling clients as soon as the SW is activated
139 | addEventListener('activate', event => {
140 | event.waitUntil(clients.claim())
141 | })
142 | ```
143 |
144 | ### Step 3: Register the ServiceWorker
145 |
146 | In your web page(s), register the ServiceWorker:
147 |
148 | ```html
149 |
153 | ```
154 |
155 | Now your web page(s) may start fetching from the server:
156 |
157 | ```js
158 | // The server will receive a request for "/path/to/resource"
159 | fetch('server/path/to/resource').then(res => {
160 | // use response...
161 | })
162 | ```
163 |
164 | ## API
165 |
166 | For Go API see [pkg.go.dev/github.com/nlepage/go-wasm-http-server](https://pkg.go.dev/github.com/nlepage/go-wasm-http-server#section-documentation)
167 |
168 | ### JavaScript API
169 |
170 | ### `registerWasmHTTPListener(wasmUrl, options)`
171 |
172 | Instantiates and runs the WebAssembly module at `wasmUrl`, and registers a fetch listener forwarding requests to the WebAssembly module's server.
173 |
174 | ⚠ This function must be called only once in a ServiceWorker, if you want to register several servers you must use several ServiceWorkers.
175 |
176 | The server will be "deployed" at the root of the ServiceWorker's scope by default, `base` may be used to deploy the server at a subpath of the scope.
177 |
178 | See [ServiceWorkerContainer.register()](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register) for more information about the scope of a ServiceWorker.
179 |
180 | #### `wasmUrl`
181 |
182 | URL string of the WebAssembly module, example: `"path/to/my-module.wasm"`.
183 |
184 | #### `options`
185 |
186 | An optional object containing:
187 |
188 | - `base` (`string`): Base path of the server, relative to the ServiceWorker's scope.
189 | - `cacheName` (`string`): Name of the [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache) to store the WebAssembly binary.
190 | - `args` (`string[]`): Arguments for the WebAssembly module.
191 | - `passthrough` (`(request: Request): boolean`): Optional callback to allow passing the request through to network.
192 |
193 | ## FAQ ❓
194 |
195 | ### Are WebSockets supported?
196 |
197 | No, WebSockets aren’t and won’t be supported, because Service Workers cannot intercept websocket connections.
198 |
199 | However [Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events), which is an alternative to WebSockets, are supported, you can find the code for an example [here](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/hello-sse) and the demo [here](https://nlepage.github.io/go-wasm-http-server/hello-sse/).
200 |
201 | ### Is it compatible with TinyGo?
202 |
203 | Yes, an example and some specific information is available [here](https://github.com/nlepage/go-wasm-http-server/tree/master/docs/tinygo).
204 |
205 | ## Contributors ✨
206 |
207 | Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
208 |
209 |
210 |
211 |
212 |
15 |
16 |
17 |
--------------------------------------------------------------------------------
/docs/tinygo/README.md:
--------------------------------------------------------------------------------
1 | # Compiling with TinyGo
2 |
3 | This example demonstrates that go-wasm-http-server can also be compiled with [TinyGo](https://www.tinygo.org), producing significantly smaller WASM blobs, though at the expense of [at least one known bug](https://github.com/tinygo-org/tinygo/issues/1140) and a [reduced standard library](https://tinygo.org/docs/reference/lang-support/stdlib/).
4 |
5 | This example also demonstrates how the same code can be used for both server-side execution, and client-side execution in WASM (providing support for clients that cannot interpret WASM).
6 |
7 | ## Prerequisites
8 |
9 | You'll need a version of [TinyGo installed](https://tinygo.org/getting-started/install/). (eg. `brew install tinygo-org/tools/tinygo`)
10 |
11 | You'll need to make sure the first line of `sw.js` here has the same tinygo version number as your TinyGo version (this was v0.35.0 at time of writing).
12 |
13 | ## Build & run
14 |
15 | Compile the WASM blob with TinyGo (this has been done for you for this example):
16 |
17 | ```bash
18 | GOOS=js GOARCH=wasm tinygo build -o api.wasm .
19 | ```
20 |
21 | Run the server (with Go, not TinyGo):
22 |
23 | ```bash
24 | $ go run .
25 | Server starting on http://127.0.0.1:
26 | ```
27 |
28 | ## Important notes
29 |
30 | You **must** use the TinyGo `wasm_exec.js`, specific to the version of TinyGo used to compile the WASM, in your `sw.js`. For example, if using the JSDelivr CDN:
31 |
32 | ```js
33 | importScripts('https://cdn.jsdelivr.net/gh/tinygo-org/tinygo@0.35.0/targets/wasm_exec.js')
34 | ```
35 |
36 | Note that the `0.35.0` within the path matches the TinyGo version used:
37 |
38 | ```sh
39 | $ tinygo version
40 | tinygo version 0.35.0 darwin/arm64 (using go version go1.23.4 and LLVM version 18.1.2)
41 | # ^----^
42 | ```
43 |
--------------------------------------------------------------------------------
/docs/tinygo/api.wasm:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/nlepage/go-wasm-http-server/9ff6ec615afc121201d7b134842bfa1a9572b86b/docs/tinygo/api.wasm
--------------------------------------------------------------------------------
/docs/tinygo/handlers.go:
--------------------------------------------------------------------------------
1 | package main
2 |
3 | import (
4 | "encoding/json"
5 | "net/http"
6 | "runtime"
7 | )
8 |
9 | func goRuntimeHandler(res http.ResponseWriter, req *http.Request) {
10 | res.Header().Add("Content-Type", "application/json")
11 | if err := json.NewEncoder(res).Encode(map[string]string{
12 | "os": runtime.GOOS,
13 | "arch": runtime.GOARCH,
14 | "compiler": runtime.Compiler,
15 | "version": runtime.Version(),
16 | }); err != nil {
17 | panic(err)
18 | }
19 | }
20 |
--------------------------------------------------------------------------------
/docs/tinygo/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | go-wasm-http-server tinygo demo
5 |
30 |
31 |
32 |
5 |
6 |
7 | 
8 |
9 | 
