https://docs.voiden.md/assets/js/1cb6d2f0.c69aa1bf.js

1"use strict";(globalThis.webpackChunkvoiden_docs=globalThis.webpackChunkvoiden_docs||[]).push([[4363],{1255:(e,t,s)=>{s.d(t,{A:()=>n});const n=s.p+"assets/images/options-req-05af5a10486a8fb33b8012b60831989f.png"},3415:(e,t,s)=>{s.d(t,{A:()=>n});const n=s.p+"assets/images/options-dfa3e8103dd5dd29dfdcbeb4b3723eab.gif"},8453:(e,t,s)=>{s.d(t,{R:()=>r,x:()=>l});var n=s(6540);const o={},i=n.createContext(o);function r(e){const t=n.useContext(i);return n.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function l(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:r(e.components),n.createElement(i.Provider,{value:t},e.children)}},9696:(e,t,s)=>{s.r(t),s.d(t,{assets:()=>c,contentTitle:()=>l,default:()=>h,frontMatter:()=>r,metadata:()=>n,toc:()=>d});const n=JSON.parse('{"id":"core-features-section/voiden-blocks/rest-blocks/options-block","title":"Options Block","description":"Global settings are great as a baseline \u2014 but sometimes a single request needs to behave differently from everything else. The Options Block gives you per-request control without touching your global config. Drop it into any section, set what you need, and Voiden handles the rest. Everything outside that section stays exactly as it was.","source":"@site/docs/core-features-section/voiden-blocks/rest-blocks/options-block.md","sourceDirName":"core-features-section/voiden-blocks/rest-blocks","slug":"/core-features-section/voiden-blocks/rest-blocks/options-block","permalink":"/docs/core-features-section/voiden-blocks/rest-blocks/options-block","draft":false,"unlisted":false,"editUrl":"https://github.com/VoidenHQ/docs/tree/main/docs/core-features-section/voiden-blocks/rest-blocks/options-block.md","tags":[],"version":"current","lastUpdatedAt":1775641279000,"frontMatter":{"id":"options-block","title":"Options Block","sidebar_label":"Options Block"},"sidebar":"tutorialSidebar","previous":{"title":"Binary File Block","permalink":"/docs/core-features-section/voiden-blocks/rest-blocks/binary-file-block"},"next":{"title":"WebSocket Block","permalink":"/docs/core-features-section/voiden-blocks/web-socket"}}');var o=s(4848),i=s(8453);const r={id:"options-block",title:"Options Block",sidebar_label:"Options Block"},l="Options Block",c={},d=[{value:"Inserting the Block",id:"inserting-the-block",level:2},{value:"How It Works",id:"how-it-works",level:2},{value:"Supported Options",id:"supported-options",level:2},{value:"Option Details",id:"option-details",level:2},{value:"<code>follow_redirects</code>",id:"follow_redirects",level:3},{value:"Precedence",id:"precedence",level:2},{value:"Scoping in Multi-Request Files",id:"scoping-in-multi-request-files",level:2},{value:"Autocomplete",id:"autocomplete",level:2},{value:"Linked Blocks",id:"linked-blocks",level:2}];function a(e){const t={admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",hr:"hr",img:"img",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,i.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(t.header,{children:(0,o.jsx)(t.h1,{id:"options-block",children:"Options Block"})}),"\n",(0,o.jsx)(t.p,{children:"Global settings are great as a baseline \u2014 but sometimes a single request needs to behave differently from everything else. The Options Block gives you per-request control without touching your global config. Drop it into any section, set what you need, and Voiden handles the rest. Everything outside that section stays exactly as it was."}),"\n",(0,o.jsx)(t.hr,{}),"\n",(0,o.jsx)(t.h2,{id:"inserting-the-block",children:"Inserting the Block"}),"\n",(0,o.jsxs)(t.p,{children:["Type ",(0,o.jsx)(t.code,{children:"/options"})," anywhere inside a ",(0,o.jsx)(t.code,{children:".void"})," file to insert the options table. It lives inline with the rest of your request \u2014 right alongside headers, body, and auth."]}),"\n",(0,o.jsx)(t.p,{children:(0,o.jsx)(t.img,{alt:"option-block",src:s(3415).A+"",width:"2452",height:"1650"})}),"\n",(0,o.jsx)(t.admonition,{type:"tip",children:(0,o.jsxs)(t.p,{children:["The options block is a ",(0,o.jsx)(t.strong,{children:"singleton per section"}),". Inserting ",(0,o.jsx)(t.code,{children:"/options"})," a second time in the same section replaces the existing table rather than stacking a second one on top."]})}),"\n",(0,o.jsx)(t.hr,{}),"\n",(0,o.jsx)(t.h2,{id:"how-it-works",children:"How It Works"}),"\n",(0,o.jsx)(t.p,{children:"Under the hood, the flow is straightforward:"}),"\n",(0,o.jsxs)(t.ol,{children:["\n",(0,o.jsxs)(t.li,{children:["When a request is sent, ",(0,o.jsx)(t.code,{children:"getRequestFromJson"})," reads all ",(0,o.jsx)(t.strong,{children:"enabled"})," rows from the ",(0,o.jsx)(t.code,{children:"options-table"})," block."]}),"\n",(0,o.jsxs)(t.li,{children:["Each row's ",(0,o.jsx)(t.code,{children:"key"})," and ",(0,o.jsx)(t.code,{children:"value"})," are collected into a ",(0,o.jsx)(t.code,{children:"Record<string, string>"})," object and attached to the request as ",(0,o.jsx)(t.code,{children:"metadata"}),"."]}),"\n",(0,o.jsxs)(t.li,{children:["The Electron main process reads ",(0,o.jsx)(t.code,{children:"metadata"})," before executing the HTTP fetch and applies any recognized options."]}),"\n",(0,o.jsxs)(t.li,{children:["Unrecognized keys are ",(0,o.jsx)(t.strong,{children:"ignored silently"})," \u2014 a typo won't break anything, but it also won't do what you expect. Use the built-in autocomplete to stay accurate."]}),"\n"]}),"\n",(0,o.jsx)(t.hr,{}),"\n",(0,o.jsx)(t.h2,{id:"supported-options",children:"Supported Options"}),"\n",(0,o.jsxs)(t.table,{children:[(0,o.jsx)(t.thead,{children:(0,o.jsxs)(t.tr,{children:[(0,o.jsx)(t.th,{children:"Key"}),(0,o.jsx)(t.th,{children:"Values"}),(0,o.jsx)(t.th,{children:"Default"}),(0,o.jsx)(t.th,{children:"Description"})]})}),(0,o.jsx)(t.tbody,{children:(0,o.jsxs)(t.tr,{children:[(0,o.jsx)(t.td,{children:(0,o.jsx)(t.code,{children:"follow_redirects"})}),(0,o.jsxs)(t.td,{children:[(0,o.jsx)(t.code,{children:"true"})," / ",(0,o.jsx)(t.code,{children:"false"})]}),(0,o.jsxs)(t.td,{children:[(0,o.jsx)(t.code,{children:"true"})," (from global settings)"]}),(0,o.jsxs)(t.td,{children:["Whether to follow HTTP 3xx redirects automatically. Set to ",(0,o.jsx)(t.code,{children:"false"})," to stop at the redirect and inspect the raw response."]})]})})]}),"\n",(0,o.jsx)(t.admonition,{type:"note",children:(0,o.jsxs)(t.p,{children:[(0,o.jsx)(t.code,{children:"timeout"})," is currently a ",(0,o.jsx)(t.strong,{children:"global-only"})," setting, configured under ",(0,o.jsx)(t.strong,{children:"Settings \u2192 Requests \u2192 Timeout"}),". It is applied at the HTTP agent level and cannot be overridden per-request via the options table yet. Only ",(0,o.jsx)(t.code,{children:"follow_redirects"})," is read from per-request metadata at this time."]})}),"\n",(0,o.jsx)(t.hr,{}

1),"\n",(0,o.jsx)(t.h2,{id:"option-details",children:"Option Details"}),"\n",(0,o.jsx)(t.h3,{id:"follow_redirects",children:(0,o.jsx)(t.code,{children:"follow_redirects"})}),"\n",(0,o.jsxs)(t.p,{children:["By default, Voiden follows redirects transparently \u2014 your request goes out, the server responds with a ",(0,o.jsx)(t.code,{children:"302"}),", and Voiden quietly chases it until it lands somewhere final. Most of the time, that's exactly what you want."]}),"\n",(0,o.jsxs)(t.p,{children:["But sometimes you need to see what's happening ",(0,o.jsx)(t.em,{children:"in between"}),". Setting ",(0,o.jsx)(t.code,{children:"follow_redirects"})," to ",(0,o.jsx)(t.code,{children:"false"})," stops Voiden at the first ",(0,o.jsx)(t.code,{children:"3xx"})," response and returns it directly \u2014 ",(0,o.jsx)(t.code,{children:"Location"})," header and all."]}),"\n",(0,o.jsx)(t.p,{children:(0,o.jsx)(t.img,{alt:"req-options",src:s(1255).A+"",width:"2452",height:"1650"})}),"\n",(0,o.jsx)(t.pre,{children:(0,o.jsx)(t.code,{children:"follow_redirects    false\n"})}),"\n",(0,o.jsxs)(t.table,{children:[(0,o.jsx)(t.thead,{children:(0,o.jsxs)(t.tr,{children:[(0,o.jsx)(t.th,{children:"Value"}),(0,o.jsx)(t.th,{children:"Behavior"})]})}),(0,o.jsxs)(t.tbody,{children:[(0,o.jsxs)(t.tr,{children:[(0,o.jsxs)(t.td,{children:[(0,o.jsx)(t.code,{children:"true"})," ",(0,o.jsx)(t.em,{children:"(default)"})]}),(0,o.jsx)(t.td,{children:"Follows all 3xx redirects transparently. Returns the final response."})]}),(0,o.jsxs)(t.tr,{children:[(0,o.jsx)(t.td,{children:(0,o.jsx)(t.code,{children:"false"})}),(0,o.jsx)(t.td,{children:"Stops at the first 3xx. Returns the redirect response directly."})]})]})]}),"\n",(0,o.jsx)(t.p,{children:(0,o.jsxs)(t.strong,{children:["When ",(0,o.jsx)(t.code,{children:"false"})," is useful:"]})}),"\n",(0,o.jsxs)(t.ul,{children:["\n",(0,o.jsxs)(t.li,{children:[(0,o.jsx)(t.strong,{children:"Debugging redirect chains"})," \u2014 see exactly where a request is being sent before the client follows it"]}),"\n",(0,o.jsxs)(t.li,{children:[(0,o.jsx)(t.strong,{children:"Verifying redirect targets"})," \u2014 confirm the ",(0,o.jsx)(t.code,{children:"Location"})," header points to the right place after a login, move, or alias"]}),"\n",(0,o.jsxs)(t.li,{children:[(0,o.jsx)(t.strong,{children:"OAuth callback flows"})," \u2014 catch the redirect carrying an auth code or token in the query string before it's consumed by the next request"]}),"\n"]}),"\n",(0,o.jsxs)(t.p,{children:["If ",(0,o.jsx)(t.code,{children:"follow_redirects"})," isn't present in the options table at all, the value falls back to the global setting under ",(0,o.jsx)(t.strong,{children:"Settings \u2192 Requests \u2192 Follow Redirects"}),"."]}),"\n",(0,o.jsx)(t.hr,{}),"\n",(0,o.jsx)(t.h2,{id:"precedence",children:"Precedence"}),"\n",(0,o.jsx)(t.p,{children:"When an options table is present, it always wins \u2014 for that request and that request only."}),"\n",(0,o.jsx)(t.pre,{children:(0,o.jsx)(t.code,{children:"per-request options-table  >  global settings\n"})}),"\n",(0,o.jsx)(t.p,{children:"The moment the request completes, the override is gone. Nothing leaks into other requests, other sections, or other files."}),"\n",(0,o.jsx)(t.hr,{}),"\n",(0,o.jsx)(t.h2,{id:"scoping-in-multi-request-files",children:"Scoping in Multi-Request Files"}),"\n",(0,o.jsxs)(t.p,{children:["Each section in a ",(0,o.jsx)(t.code,{children:".void"})," file owns its options independently. An options block in one section has zero effect on any other \u2014 they don't share state or inherit from each other."]}),"\n",(0,o.jsx)(t.pre,{children:(0,o.jsx)(t.code,{children:"GET https://api.example.com/login\n[options]\nfollow_redirects    false\n# Stops at the redirect \u2014 grab the Location header directly\n\n---\n\nGET https://api.example.com/dashboard\n# No options block \u2014 falls back to the global follow_redirects setting\n"})}),"\n",(0,o.jsx)(t.p,{children:"This makes it easy to test different behaviors side by side in the same file without them interfer

1ing with each other."}),"\n",(0,o.jsx)(t.hr,{}),"\n",(0,o.jsx)(t.h2,{id:"autocomplete",children:"Autocomplete"}),"\n",(0,o.jsx)(t.p,{children:"The key column has built-in autocomplete. Start typing in the first cell and Voiden shows all supported option keys with short descriptions inline. It's the fastest way to discover what's available and avoid silent misses from typos."}),"\n",(0,o.jsx)(t.hr,{}),"\n",(0,o.jsx)(t.h2,{id:"linked-blocks",children:"Linked Blocks"}),"\n",(0,o.jsxs)(t.p,{children:["Like headers, query params, and auth, the options table supports ",(0,o.jsx)(t.strong,{children:"block linking"}),". Link a shared options configuration from another file so multiple requests can reuse the same settings without duplication."]}),"\n",(0,o.jsxs)(t.p,{children:["If the source file changes, linked blocks display a ",(0,o.jsx)(t.strong,{children:"source sync indicator"})," \u2014 so you always know when you're looking at something that might be out of date."]})]})}function h(e={}){const{wrapper:t}={...(0,i.R)(),...e.components};return t?(0,o.jsx)(t,{...e,children:(0,o.jsx)(a,{...e})}):a(e)}}}]);