ft: add functions-loopback flag for Docker

[hrishikesh-k]

Fixes: https://netlify.zendesk.com/agent/tickets/350390 and in-turn: https://netlify.slack.com/archives/C07686YAY13/p1741885987341759

When running netlify dev or netlify functions:serve inside Docker and visiting the Function's URL, the CLI fails with an error like:

Error: connect ECONNREFUSED [127.0.0.1:41493](http://127.0.0.1:41493/)
Error: connect ECONNREFUSED [127.0.0.1:41493](http://127.0.0.1:41493/)
   at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1634:16)

where the port number could be different everytime. Upon investigation, it was discovered that this is becauce:

• we create a worker that always tries to connect to 127.0.0.1
• in Docker, for some reason the loopback address is ::1

So essentially, we were trying to connect on IPv4 when the only available connection was on IPv6. This PR now adds --functions-loopback flag to:

• netlify dev
• netlify functions:invoke
• netlify functions:serve
• netlify serve

This flag is optional and can accept either:

• 127.0.0.1 (default)
• OR ::1

So in Docker, users can now use netlify dev --functions-loopback="::1" to get past the issue.

I'm not sure about the tests for this. If someone else can think of any relevant tests to add, feel free to add those.

I tried to update the docs, however when running npm run docs, I first got an error: markdown-magic is missing. I installed the package as a dev dependency, but then it wasn't working as it seems we still need v2 of the package. v3 has some breaking changes and the current code is not meant for it. So i switch to v2, however it still fails with:

npm run docs

> [email protected] docs
> npm run --prefix=site build


> [email protected] build
> npm run build:docs-md && npm run build:site


> [email protected] build:docs-md
> npm run build:docs-md:gen && npm run build:docs-md:copy


> [email protected] build:docs-md:gen
> ./scripts/docs.js

/home/hrishikesh/netlify/cli/node_modules/async-function/require.mjs:2
var __create=Object.create;var __defProp=Object.defineProperty;var __getOwnPropDesc=Object.getOwnPropertyDescriptor;var __getOwnPropNames=Object.getOwnPropertyNames;var __getProtoOf=Object.getPrototypeOf;var __ha
sOwnProp=Object.prototype.hasOwnProperty;var __export=(target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:true})};var __copyProps=(to,from,except,desc)=>{if(from&&typeof from==="obj
ect"||typeof from==="function"){for(let key of __getOwnPropNames(from))if(!__hasOwnProp.call(to,key)&&key!==except)__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerabl
e})}return to};var __toESM=(mod,isNodeMode,target)=>(target=mod!=null?__create(__getProtoOf(mod)):{},__copyProps(isNodeMode||!mod||!mod.__esModule?__defProp(target,"default",{value:mod,enumerable:true}):target,mo
d));var __toCommonJS=mod=>__copyProps(__defProp({},"__esModule",{value:true}),mod);var require_exports={};__export(require_exports,{default:()=>require_default,"module.exports":()=>import_index.default});module.exports=__toCommonJS(require_exports);var import_index=__toESM(require("./index.js"));var require_default=import_index.default;0&&(module.exports={"module.exports"});
                                                                                                                                                                                                                    
                                                                                                                                                                                                                    
                                                                                                                                                                                                                    
                                                                                                                                                                                                                    


SyntaxError: Unexpected string
    at wrapSafe (node:internal/modules/cjs/loader:1486:18)
    at Module._compile (node:internal/modules/cjs/loader:1528:20)
    at Object.transformer (/home/hrishikesh/.npm/_npx/fd45a72a545557e9/node_modules/tsx/dist/register-DCnOAxY2.cjs:2:1186)
    at Module.load (node:internal/modules/cjs/loader:1289:32)
    at Function._load (node:internal/modules/cjs/loader:1108:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:220:24)
    at Module.require (node:internal/modules/cjs/loader:1311:12)
    at require (node:internal/modules/helpers:136:16)
    at Object.<anonymous> (/home/hrishikesh/netlify/cli/node_modules/is-async-function/index.js:13:20)

Node.js v22.14.0

That's outside my skill level and the scope of this PR to debug and fix, so I haven't updated the docs.

Note: The name/values of the flag is open for discussion.

[github-actions]

📊 Benchmark results

Comparing with 32ee8c0

• Dependency count: 1,167 ⬇️ 0.09% decrease vs. 32ee8c0
• Package size: 279 MB ⬇️ 0.36% decrease vs. 32ee8c0
• Number of ts-expect-error directives: 716 (no change)

[hrishikesh-k]

An example Dockerfile to test this:

FROM ubuntu AS base
RUN apt update
RUN apt upgrade -y
RUN apt install -y curl gpg wget
RUN install -dm 755 /etc/apt/keyrings
RUN wget -qO - https://mise.jdx.dev/gpg-key.pub | gpg --dearmor | tee /etc/apt/keyrings/mise-archive-keyring.gpg 1> /dev/null
RUN echo "deb [signed-by=/etc/apt/keyrings/mise-archive-keyring.gpg arch=arm64] https://mise.jdx.dev/deb stable main" | tee /etc/apt/sources.list.d/mise.list
RUN apt update
RUN apt install -y mise
RUN mise use -g [email protected] node@22
WORKDIR /ntl
RUN mkdir -p "netlify/functions"
RUN echo "{\"type\": \"module\"}" > "package.json"
RUN echo "export default async () => Response.json({ a: 1 });" > "netlify/functions/a.ts"
RUN mise exec node@22 -- npm i netlify-cli @netlify/functions
CMD ["mise", "exec", "node@22", "--", "npx", "netlify", "dev", "--functions-loopback=\"::1"\"]

Creating a container by building this and exposing the port 8888:8888 should do it. You can then open another terminal window and run:

curl "http://localhost:8888/.netlify/functions/a"

[mabels]

Hi,

I retested it, and now it looks like it works as expected.

thx

Meno(fireproof)