caddy-subdomain 0.0.0-stage β 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +15 -0
- package/README.md +297 -2
- package/bin/index.js +5 -0
- package/docs/index.html +365 -0
- package/docs/npx/add.html +156 -0
- package/docs/npx/check.html +137 -0
- package/docs/npx/index.html +196 -0
- package/docs/npx/list.html +111 -0
- package/docs/npx/probe.html +212 -0
- package/package.json +44 -3
- package/src/cli.js +2 -0
- package/src/index.js +1 -0
- package/src/v1/cli.js +255 -0
- package/src/v1/index.js +300 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) KeshavSoft
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
6
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
7
|
+
copyright notice and this permission notice appear in all copies.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
|
10
|
+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
11
|
+
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
12
|
+
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
|
13
|
+
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
|
|
14
|
+
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
15
|
+
PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,298 @@
|
|
|
1
|
-
#
|
|
1
|
+
# caddy-subdomain
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/caddy-subdomain)
|
|
4
|
+
[](https://opensource.org/licenses/ISC)
|
|
5
|
+
[](https://keshavsoft.github.io/caddy-subdomain/)
|
|
6
|
+
[](https://github.com/keshavsoft/caddy-subdomain)
|
|
7
|
+
[](https://caddyserver.com/docs/)
|
|
8
|
+
|
|
9
|
+
> **The Single-Purpose Subdomain Engine for Caddy JSON.**
|
|
10
|
+
> Safely test DNS & automatic HTTPS with zero-dependency smoke probes, then promote to reverse proxies with automatic backups and zero downtime.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## π Table of Contents
|
|
15
|
+
|
|
16
|
+
- [The Subdomain Lifecycle](#-the-subdomain-lifecycle)
|
|
17
|
+
- [Level 1: The Smoke Test Probe (Zero Dependencies)](#level-1-the-smoke-test-probe-zero-dependencies)
|
|
18
|
+
- [Level 2: Promote to Backend Reverse Proxy](#level-2-promote-to-backend-reverse-proxy)
|
|
19
|
+
- [Interactive Documentation Portal](#-interactive-documentation-portal)
|
|
20
|
+
- [Quick Start with `npx`](#-quick-start-with-npx)
|
|
21
|
+
- [CLI Command Reference](#-cli-command-reference)
|
|
22
|
+
- [`caddy-subdomain probe`](#1-caddy-subdomain-probe-domain)
|
|
23
|
+
- [`caddy-subdomain add`](#2-caddy-subdomain-add-domain-port)
|
|
24
|
+
- [`caddy-subdomain list`](#3-caddy-subdomain-list-configpath)
|
|
25
|
+
- [`caddy-subdomain check`](#4-caddy-subdomain-check-domain)
|
|
26
|
+
- [Programmatic ESM Library Reference](#-programmatic-esm-library-reference)
|
|
27
|
+
- [Safety & Auto-Backups](#-safety--auto-backups)
|
|
28
|
+
- [Troubleshooting & FAQ](#-troubleshooting--faq)
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## π§ The Subdomain Lifecycle
|
|
33
|
+
|
|
34
|
+
When creating a new subdomain (e.g. on GoDaddy, Cloudflare, or Namecheap), trying to configure your Node.js application, ports, Caddy reverse proxy, and SSL certificate all at the same time is prone to frustrating connection errors.
|
|
35
|
+
|
|
36
|
+
`caddy-subdomain` introduces a **two-stage verification workflow**:
|
|
37
|
+
|
|
38
|
+
```mermaid
|
|
39
|
+
flowchart TD
|
|
40
|
+
DNS["1. GoDaddy / DNS Provider<br>Add A Record: call β 103.174.102.116"]
|
|
41
|
+
DNS --> Probe["2. Level 1: Caddy Probe<br>npx caddy-subdomain probe call.keshavsoft.com"]
|
|
42
|
+
Probe --> Verify{"3. Visit https://call.keshavsoft.com"}
|
|
43
|
+
Verify -->|Green Padlock + 200 OK| Promoted["4. Level 2: Promote to Node.js<br>npx caddy-subdomain add call.keshavsoft.com 5000"]
|
|
44
|
+
Verify -->|Connection Error| FixDNS["Fix DNS propagation or Port 443 firewall<br>(Node app wasn't even touched!)"]
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
### Level 1: The Smoke Test Probe (Zero Dependencies)
|
|
50
|
+
Before starting Node.js or allocating ports, verify that **DNS points to your server** and that **Caddy's Automatic HTTPS issued an SSL certificate**:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npx caddy-subdomain probe call.keshavsoft.com
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**How it works under the hood:**
|
|
57
|
+
- **Zero Config Passing:** Automatically discovers `/etc/caddy/caddy.json` on your VPS or `./caddy.json` locally.
|
|
58
|
+
- **Automatic Reload:** Executes hot-reload automatically without needing flags.
|
|
59
|
+
- **Zero Port/Process Overhead:** Injects a native Caddy `static_response` handler (HTTP 200 OK).
|
|
60
|
+
- **Direct Terminal Feedback:**
|
|
61
|
+
```text
|
|
62
|
+
Subdomain: call.keshavsoft.com
|
|
63
|
+
Present in Caddy: Yes (Probe Active)
|
|
64
|
+
Caddy Reload: Success
|
|
65
|
+
Live HTTPS: Yes (200 OK - Verified)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
### Level 2: Promote to Backend Reverse Proxy
|
|
71
|
+
Now that the domain and SSL certificate are proven live, promote the subdomain to your actual application:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
npx caddy-subdomain add call.keshavsoft.com 5000
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
- Replaces the probe with a clean `reverse_proxy` pointing to `localhost:5000`.
|
|
78
|
+
- Automatically executes hot-reload in memory.
|
|
79
|
+
- Retains existing TLS certificatesβzero re-negotiation downtime!
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## π Interactive Documentation Portal
|
|
84
|
+
|
|
85
|
+
Explore live examples, visual flowcharts, and the interactive command builder:
|
|
86
|
+
π **[https://keshavsoft.github.io/caddy-subdomain/](https://keshavsoft.github.io/caddy-subdomain/)**
|
|
87
|
+
π Dedicated NPX Command Catalog: **[https://keshavsoft.github.io/caddy-subdomain/npx/](https://keshavsoft.github.io/caddy-subdomain/npx/)**
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## π Quick Start with `npx`
|
|
92
|
+
|
|
93
|
+
Zero installation and zero path configuration required:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
# 1. Probe a new domain (Level 1 Flight Check: auto-detects config & auto-reloads)
|
|
97
|
+
npx caddy-subdomain probe call.keshavsoft.com
|
|
98
|
+
|
|
99
|
+
# 2. Add or promote to a Node / Python / Go backend port
|
|
100
|
+
npx caddy-subdomain add call.keshavsoft.com 5000
|
|
101
|
+
|
|
102
|
+
# 3. Check if a domain already exists in Caddy (Instant Yes / No answer)
|
|
103
|
+
npx caddy-subdomain check call.keshavsoft.com
|
|
104
|
+
|
|
105
|
+
# 4. List all configured subdomains
|
|
106
|
+
npx caddy-subdomain list
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## βοΈ CLI Command Reference
|
|
112
|
+
|
|
113
|
+
### Default Config Resolution
|
|
114
|
+
`caddy-subdomain` automatically checks in priority order:
|
|
115
|
+
1. `/etc/caddy/caddy.json` (standard Linux/VPS path).
|
|
116
|
+
2. `./caddy.json` in current directory.
|
|
117
|
+
3. Sibling/parent configuration files.
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
### 1. `caddy-subdomain probe <domain>`
|
|
122
|
+
Injects a Level-1 test probe route, auto-reloads Caddy, and probes live HTTPS:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
npx caddy-subdomain probe call.keshavsoft.com
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**Terminal Output:**
|
|
129
|
+
```text
|
|
130
|
+
Subdomain: call.keshavsoft.com
|
|
131
|
+
Present in Caddy: Yes (Probe Active)
|
|
132
|
+
Caddy Reload: Success
|
|
133
|
+
Live HTTPS: Yes (200 OK - Verified)
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
### 2. `caddy-subdomain add <domain> <port>`
|
|
139
|
+
Appends or updates a reverse proxy route forwarding traffic to your backend target:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
npx caddy-subdomain add call.keshavsoft.com 5000
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
**Terminal Output:**
|
|
146
|
+
```text
|
|
147
|
+
Subdomain: call.keshavsoft.com
|
|
148
|
+
Target: localhost:5000
|
|
149
|
+
Caddy Reload: Success
|
|
150
|
+
Status: Active
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
### 3. `caddy-subdomain check <domain>`
|
|
156
|
+
Direct presence check. Returns a clean binary **Yes** or **No**:
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
npx caddy-subdomain check call.keshavsoft.com
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
**Terminal Output:**
|
|
163
|
+
```text
|
|
164
|
+
Subdomain: call.keshavsoft.com
|
|
165
|
+
Present in Caddy: Yes
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
### 4. `caddy-subdomain list`
|
|
171
|
+
Prints an indexed list of every unique subdomain registered in Caddy:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
npx caddy-subdomain list
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
**Terminal Output:**
|
|
178
|
+
```text
|
|
179
|
+
Config: /etc/caddy/caddy.json
|
|
180
|
+
Subdomains (3):
|
|
181
|
+
1. quotation.keshavsoft.com
|
|
182
|
+
2. call.keshavsoft.com
|
|
183
|
+
3. appointment.keshavsoft.com
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## π¦ Programmatic ESM Library Reference
|
|
189
|
+
|
|
190
|
+
Use `caddy-subdomain` directly in your Node.js scripts and microservices:
|
|
191
|
+
|
|
192
|
+
```javascript
|
|
193
|
+
import {
|
|
194
|
+
readCaddyConfig,
|
|
195
|
+
writeCaddyConfig,
|
|
196
|
+
listSubdomains,
|
|
197
|
+
hasSubdomain,
|
|
198
|
+
buildProbeRoute,
|
|
199
|
+
addProbeSubdomainToFile,
|
|
200
|
+
buildProxyRoute,
|
|
201
|
+
addSubdomainToFile
|
|
202
|
+
} from "caddy-subdomain";
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Methods
|
|
206
|
+
|
|
207
|
+
#### `readCaddyConfig(filePath)`
|
|
208
|
+
Safely loads and parses Caddy JSON.
|
|
209
|
+
```javascript
|
|
210
|
+
const config = readCaddyConfig("./caddy.json");
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
#### `listSubdomains(config)`
|
|
214
|
+
Returns an array of unique domain strings: `string[]`.
|
|
215
|
+
```javascript
|
|
216
|
+
const domains = listSubdomains(config);
|
|
217
|
+
// ['api.keshavsoft.com', 'call.keshavsoft.com']
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
#### `hasSubdomain(config, domain)`
|
|
221
|
+
Returns boolean `true` if domain exists (case-insensitive).
|
|
222
|
+
```javascript
|
|
223
|
+
if (hasSubdomain(config, "call.keshavsoft.com")) {
|
|
224
|
+
console.log("Domain taken!");
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
#### `addProbeSubdomainToFile(filePath, options)`
|
|
229
|
+
Adds Level-1 probe route to file with backup.
|
|
230
|
+
```javascript
|
|
231
|
+
const result = addProbeSubdomainToFile("/etc/caddy/caddy.json", {
|
|
232
|
+
domain: "call.keshavsoft.com",
|
|
233
|
+
backup: true
|
|
234
|
+
});
|
|
235
|
+
console.log(result.backupFile); // /etc/caddy/caddy.json.bak.1795123000
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
#### `addSubdomainToFile(filePath, options)`
|
|
239
|
+
Adds Level-2 reverse proxy route to file with backup.
|
|
240
|
+
```javascript
|
|
241
|
+
const result = addSubdomainToFile("/etc/caddy/caddy.json", {
|
|
242
|
+
domain: "call.keshavsoft.com",
|
|
243
|
+
port: 5000,
|
|
244
|
+
force: true, // Replaces the Level-1 probe
|
|
245
|
+
backup: true
|
|
246
|
+
});
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## π‘οΈ Safety & Auto-Backups
|
|
252
|
+
|
|
253
|
+
Whenever a write operation occurs (`add` or `probe`), `caddy-subdomain` writes a timestamped snapshot before touching the live file:
|
|
254
|
+
|
|
255
|
+
```text
|
|
256
|
+
/etc/caddy/
|
|
257
|
+
βββ caddy.json # Active live config
|
|
258
|
+
βββ caddy.json.bak.1795132001 # Backup created before probe
|
|
259
|
+
βββ caddy.json.bak.1795132500 # Backup created before promote
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
If an issue ever occurs, restoring is as simple as:
|
|
263
|
+
```bash
|
|
264
|
+
cp /etc/caddy/caddy.json.bak.<timestamp> /etc/caddy/caddy.json
|
|
265
|
+
caddy reload --config /etc/caddy/caddy.json
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
## β Troubleshooting & FAQ
|
|
271
|
+
|
|
272
|
+
### 1. Probe route returns connection refused in browser
|
|
273
|
+
- **Cause**: DNS hasn't propagated yet or VPS firewall is blocking port 80 / 443.
|
|
274
|
+
- **Verification**: Run `nslookup call.keshavsoft.com` on your local PC. Ensure the IP matches your VPS. Ensure ports 80 and 443 are open (`ufw allow 80 && ufw allow 443`).
|
|
275
|
+
|
|
276
|
+
### 2. Can Caddy issue SSL certificates for private IP addresses?
|
|
277
|
+
- **Answer**: No, Let's Encrypt and ZeroSSL require a public DNS A/AAAA record pointing to a public IP address (such as your GoDaddy DNS record).
|
|
278
|
+
|
|
279
|
+
### 3. How do I switch a probe to my Node.js application?
|
|
280
|
+
- Run `add` with `--force`:
|
|
281
|
+
```bash
|
|
282
|
+
npx caddy-subdomain add <domain> <port> --force --reload
|
|
283
|
+
```
|
|
284
|
+
`--force` seamlessly replaces the static probe route with the reverse proxy.
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
## π The KeshavSoft Caddy Suite
|
|
289
|
+
|
|
290
|
+
- **[caddy-subdomain](https://github.com/keshavsoft/caddy-subdomain)**: Subdomain management, smoke probes, and collision detection.
|
|
291
|
+
- **[caddy-template](https://github.com/keshavsoft/caddy-template)**: Battle-tested Caddy JSON route blueprints.
|
|
292
|
+
- **[caddy-cli](https://github.com/keshavsoft/caddy-cli)**: High-level orchestrator and port inspector.
|
|
293
|
+
|
|
294
|
+
---
|
|
295
|
+
|
|
296
|
+
## π License
|
|
297
|
+
|
|
298
|
+
[ISC](LICENSE) © [KeshavSoft](https://github.com/keshavsoft)
|