{"errors":[],"data":[{"views":1482,"title":"Perfect Gradients in CSS via Easing and the LAB Color Space","tags":[{"title":"Design","slug":{"current":"design","_type":"slug"},"_id":"600e7ca1-a799-47de-937e-69254e2b3ab9"},{"title":"CSS","slug":{"current":"css","_type":"slug"},"_id":"babd9448-7c2c-4cf2-b900-e4845ca99d87"},{"title":"Guides","slug":{"current":"guides","_type":"slug"},"_id":"4501a332-2a0c-4baf-8281-bf59862a250d"}],"slug":{"current":"perfect-gradients-in-css-via-easing-and-the-lab-color-space","_type":"slug"},"numberOfCharacters":5672,"headings":[{"typeLevel":1,"children":[],"key":"b7018d161b26","text":"Linear vs Eased Interpolation","type":"h1","parent":null},{"typeLevel":1,"children":[{"typeLevel":2,"children":[],"key":"9c2def67c657","text":"SCSS Functions","type":"h2","parent":"5cda758841b0"}],"key":"5cda758841b0","text":"Easing Gradients","type":"h1","parent":null},{"typeLevel":1,"children":[{"typeLevel":2,"children":[],"key":"ad7a4572edd9","text":"What is the LAB Colour Space?","type":"h2","parent":"96780423eacc"},{"typeLevel":2,"children":[],"key":"3c471d49c290","text":"Implementing LAB Color Interpolation in SCSS","type":"h2","parent":"96780423eacc"}],"key":"96780423eacc","text":"Fixing RGB Colour Mixing","type":"h1","parent":null},{"typeLevel":1,"children":[],"key":"cf8f6ead7c36","text":"Fin","type":"h1","parent":null}],"estimatedWordCount":1134,"estimatedReadingTime":9,"desc":"Benefits of easing linear gradients in CSS and using LAB colour space to create smoother and more visually pleasing colour transitions.","date":"2024-06-23","body":[{"style":"h1","markDefs":[],"children":[{"text":"Linear vs Eased Interpolation","marks":[],"_type":"span","_key":"c374ee303a79"}],"_type":"block","_key":"b7018d161b26"},{"style":"normal","markDefs":[],"children":[{"text":"The ","marks":[],"_type":"span","_key":"1da8b74e7c200"},{"text":"linear-gradient","marks":["code"],"_type":"span","_key":"1da8b74e7c201"},{"text":" function in CSS interpolates colours linearly between provided stops along a line. This linear-ness can produce gradients that look uneven or harsh, especially between few stops, colours with different luminance or saturation levels, or when working with transparency. Assuming a constant rate of change between colours doesn't always align with how we perceive colour differences. The human eye is more sensitive to changes in certain colour ranges, which can make a purely linear transition look unnatural. This also applies to the colour values chosen in-between stops when mixing in the RGB colour space, as I'll detail later.","marks":[],"_type":"span","_key":"1da8b74e7c202"}],"_type":"block","_key":"d6a8783c9a80"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"b991c24f1a86"}],"_type":"block","_key":"83fde7d4c37a"},{"style":"normal","markDefs":[],"children":[{"text":"Easing functions can be applied to colour transitions to create more natural and visually-pleasing gradients. These functions adjust the rate of change, making the transition smoother and more gradual. By easing between multiple colour stops within ","marks":[],"_type":"span","_key":"63f20e23be020"},{"text":"linear-gradient","marks":["code"],"_type":"span","_key":"33eae92ef610"},{"text":", the gradient progression can be made to more closely mimic natural colour blending, resulting in a more harmonious look.","marks":[],"_type":"span","_key":"a8b3aa6e3052"}],"_type":"block","_key":"184f4dbc723a"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"a021490c5f60"}],"_type":"block","_key":"c858922c355e"},{"style":"normal","markDefs":[],"children":[{"text":"Here's a visual example – the same two colours over a white background, interpolated linearly and with an easing function applied:","marks":[],"_type":"span","_key":"0be95dbc4cdd"}],"_type":"block","_key":"e8dad8a75a3a"},{"asset":{"_type":"reference","_ref":"image-0633ade059c5239737a076c139e5938c7c9847d9-1589x749-png"},"_type":"image","_key":"2103740e4006"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"93c4b79fa476"}],"_type":"block","_key":"59a6e6520c8a"},{"asset":{"_type":"reference","_ref":"image-beb8268195a014c7b46edf465a9cefe4a0dc1c70-1589x749-png"},"_type":"image","_key":"92d69757d0ec"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"5b36c063e7b5"}],"_type":"block","_key":"3a79b8fa5ba8"},{"style":"normal","markDefs":[],"children":[{"text":"The first bar uses linear interpolation, and doesn't appear visually-balanced. The colours bleed into each other nearly right away. Using an 'ease-in-out' function, the second appears much more even and visually-pleasing as a transition between two colours.","marks":[],"_type":"span","_key":"6d35d59cc5e9"}],"_type":"block","_key":"89123ec423f4"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"5b1d3affc331"}],"_type":"block","_key":"2a29fcb1bcb0"},{"style":"normal","markDefs":[],"children":[{"text":"The unpleasing dirty-looking mix in the middle is another issue, to do with how colours are blended in the RGB colour space in CSS. However, it's visible how the start and end are much more vibrant, clearly closer to the original colours, and mixing begins closer to the centre.","marks":[],"_type":"span","_key":"c2b3779f10eb"}],"_type":"block","_key":"07cf3ae10ae6"},{"style":"h1","markDefs":[],"children":[{"text":"Easing Gradients","marks":[],"_type":"span","_key":"02ca0223d9c7"}],"_type":"block","_key":"5cda758841b0"},{"style":"normal","markDefs":[],"children":[{"text":"Implementing eased linear gradients in vanilla CSS involves manually calculating the eased positions for each color stop. The above two examples are written as:","marks":[],"_type":"span","_key":"85d5bae0879b0"}],"_type":"block","_key":"63bdb0035df3"},{"language":"css","code":"background: linear-gradient(90deg, #595650, #ff4800);","_type":"code","_key":"e94053a38b0a"},{"language":"css","code":"background: linear-gradient(90deg, #595650 0%, #595650 5.2631578947%, #5b564f 10.5263157895%, #5d564e 15.7894736842%, #60554c 21.0526315789%, #64554a 26.3157894737%, #6a5548 31.5789473684%, #705445 36.8421052632%, #765442 42.1052631579%, #7e533e 47.3684210526%, #87523a 52.6315789474%, #915135 57.8947368421%, #9b5030 63.1578947368%, #a74f2b 68.4210526316%, #b34e25 73.6842105263%, #c04d1e 78.9473684211%, #cf4c17 84.2105263158%, #de4b10 89.4736842105%, #ee4908 94.7368421053%, #ff4800 100%);","_type":"code","_key":"18f054e1eda2"},{"style":"normal","markDefs":[],"children":[{"text":"While certainly possible to do, it's a tedious and error-prone process - not really feasable for large projects and painful to update in the future. ","marks":[],"_type":"span","_key":"8fa5c7220a9d"}],"_type":"block","_key":"ab8ab9dbf2c7"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"120992b07784"}],"_type":"block","_key":"ce5326f6f1bf"},{"style":"normal","markDefs":[],"children":[{"text":"Thankfully, it's fairly straightforward to leverage SCSS functions for automating the creation of such eased gradients.","marks":[],"_type":"span","_key":"cc16846fb02d"}],"_type":"block","_key":"0a47651792b0"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"77f4718df80c"}],"_type":"block","_key":"cea29450563f"},{"style":"h2","markDefs":[],"children":[{"text":"SCSS Functions","marks":[],"_type":"span","_key":"5cd289c9db91"}],"_type":"block","_key":"9c2def67c657"},{"style":"normal","markDefs":[],"children":[{"text":"First, we define an easing function to determine the rate of change for each colour stop. A basic 'ease' function looks like:","marks":[],"_type":"span","_key":"5e9e880118120"}],"_type":"block","_key":"25c73c744ce0"},{"language":"scss","code":"@function ease($t) {\n @return $t * $t;\n}","_type":"code","_key":"a1a1d25c9297"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"91e625482877"}],"_type":"block","_key":"e6f6e2bf9f06"},{"style":"normal","markDefs":[],"children":[{"text":"An 'ease-in-out' function is also fairly simple and is what I settled on using as it provides the best-looking results:","marks":[],"_type":"span","_key":"49a67b5a6eb4"}],"_type":"block","_key":"eadc9696c463"},{"language":"scss","code":"@function ease-in-out($t) {\n @if ($t < 0.5) {\n @return 2 * $t * $t;\n } @else {\n @return -1 + (4 - 2 * $t) * $t;\n }\n}","_type":"code","_key":"7b7efaf9f641"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"0aa729d598ac"}],"_type":"block","_key":"189e6e3c095d"},{"style":"normal","markDefs":[],"children":[{"text":"Next, a function that generates the ","marks":[],"_type":"span","_key":"53154f5b792d0"},{"text":"linear-gradient","marks":["code"],"_type":"span","_key":"53154f5b792d1"},{"text":" rule using the easing function:","marks":[],"_type":"span","_key":"53154f5b792d2"}],"_type":"block","_key":"caec20c50874"},{"language":"scss","code":"@function ease-gradient($dir, $color1, $color2) {\n $stops: 20; // Number of stops for a smoother gradient\n $percentage-step: 100% / ($stops - 1);\n $gradient: '';\n\n @for $i from 0 through ($stops - 1) {\n $percentage: $i * $percentage-step;\n $eased-percentage: ease($percentage / 100);\n $interpolated-color: mix($color2, $color1, $eased-percentage * 100%);\n @if $i == 0 {\n $gradient: '#{$interpolated-color} #{$percentage}';\n } @else {\n $gradient: '#{$gradient}, #{$interpolated-color} #{$percentage}';\n }\n }\n\n $gradient-string: unquote('linear-gradient(#{$dir}, #{$gradient})');\n @return $gradient-string;\n}","_type":"code","_key":"3ad76833eaff"},{"style":"normal","markDefs":[],"children":[{"text":"This function wraps our easing function, positioning each stop and mixing the colours appropriately. For simplicity, it only handles a start-colour and end-colour, although it wouldn't be too hard to take in a list of colours / positions, just as CSS's ","marks":[],"_type":"span","_key":"e81075e46b820"},{"text":"linear-gradient","marks":["code"],"_type":"span","_key":"d3a270c3bd07"},{"text":" does.","marks":[],"_type":"span","_key":"255f5c3eca13"}],"_type":"block","_key":"45c84788793c"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"a8b091aeac12"}],"_type":"block","_key":"73b6b6d05caf"},{"style":"h1","markDefs":[],"children":[{"text":"Fixing RGB Colour Mixing","marks":[],"_type":"span","_key":"6d3657185cee"}],"_type":"block","_key":"96780423eacc"},{"style":"normal","markDefs":[],"children":[{"text":"As mentioned prior, when creating gradients between two complimentary colours, such as purple and green, you might encounter dirty or muddy colors in the middle due to the way colors are interpolated in the RGB colour space. This is because the RGB colour space does not account for human perception of colour differences. To achieve smoother and more visually appealing gradients, we can use the LAB colour space, which is designed to be more perceptually uniform.","marks":[],"_type":"span","_key":"ef9bb7fa15d0"}],"_type":"block","_key":"f148ede672d7"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"7833344496c7"}],"_type":"block","_key":"9f7b86b9fd23"},{"style":"h2","markDefs":[],"children":[{"text":"What is the LAB Colour Space?","marks":[],"_type":"span","_key":"98f21ac181120"}],"_type":"block","_key":"ad7a4572edd9"},{"style":"normal","markDefs":[],"children":[{"text":"The LAB colour space (CIELAB) is a color space that describes colours more simillarly to how humans perceive them. It consists of three components:","marks":[],"_type":"span","_key":"87abf10ebfaa0"}],"_type":"block","_key":"3b134bb6667a"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"L","marks":["strong"],"_type":"span","_key":"09ecb554434c0"},{"text":": Lightness (0 to 100)","marks":[],"_type":"span","_key":"09ecb554434c1"}],"_type":"block","_key":"35586fc28c2c"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"A","marks":["strong"],"_type":"span","_key":"809ff427a1e20"},{"text":": Green to red (-128 to 127)","marks":[],"_type":"span","_key":"809ff427a1e21"}],"_type":"block","_key":"0aca76485e3e"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"B","marks":["strong"],"_type":"span","_key":"3ef86b3669420"},{"text":": Blue to yellow (-128 to 127)","marks":[],"_type":"span","_key":"3ef86b3669421"}],"_type":"block","_key":"18104c3e816c"},{"style":"normal","markDefs":[],"children":[{"text":"Unlike the RGB colour space, which is device-dependent and based on mixing red, green, and blue light, the LAB colour space is designed to be perceptually uniform. This means that a given numerical change in LAB values corresponds to a similar perceived change in colour. This makes it ideal for tasks like colour interpolation, where the goal is to create smooth and natural transitions.","marks":[],"_type":"span","_key":"ffd1256e8a810"}],"_type":"block","_key":"d33921bea20e"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"a5b0e5c9ad43"}],"_type":"block","_key":"25fe4fdaadf7"},{"style":"normal","markDefs":[],"children":[{"text":"Here's some visual examples of mixing between values in RGB vs in LAB. Which do you think look more pleasing? 🙃","marks":[],"_type":"span","_key":"3094bdb25a7e"}],"_type":"block","_key":"ee01296b733c"},{"asset":{"_type":"reference","_ref":"image-4e39ec55a01c553139bc90ce18741de5e3aaef96-1589x749-png"},"_type":"image","_key":"c1bfb093221a"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"c3c1cf50384b"}],"_type":"block","_key":"a31573009aa4"},{"asset":{"_type":"reference","_ref":"image-a5ebc6bb1f3ab90c9c2ffd7f69b2e281fd40b9ec-1589x749-png"},"_type":"image","_key":"eecb751d3ba5"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"dd8e3722de1f"}],"_type":"block","_key":"687ce43c32f8"},{"style":"h2","markDefs":[],"children":[{"text":"Implementing LAB Color Interpolation in SCSS","marks":[],"_type":"span","_key":"27585ef8975e0"}],"_type":"block","_key":"3c471d49c290"},{"style":"normal","markDefs":[],"children":[{"text":"To interpolate colours in the LAB color space, we first need to convert RGB colours to LAB, perform the interpolation, and then convert the LAB colours back to RGB for insertion into the ","marks":[],"_type":"span","_key":"84776da68c8a0"},{"text":"linear-gradient","marks":["code"],"_type":"span","_key":"a3e5994a7fd3"},{"text":" string. ","marks":[],"_type":"span","_key":"57dcf0453837"}],"_type":"block","_key":"1d5ef08bb197"},{"style":"normal","markDefs":[],"children":[{"text":"Below are functions for these conversions - RGB to LAB and vice versa:","marks":[],"_type":"span","_key":"f8e467461e96"}],"_type":"block","_key":"d3a0b944e048"},{"language":"scss","code":"@function rgb-to-lab($color) {\n $r: red($color) / 255;\n $g: green($color) / 255;\n $b: blue($color) / 255;\n\n // RGB to XYZ\n @if $r > 0.04045 {\n $r: pow((($r + 0.055) / 1.055), 2.4);\n } @else {\n $r: $r / 12.92;\n }\n\n @if $g > 0.04045 {\n $g: pow((($g + 0.055) / 1.055), 2.4);\n } @else {\n $g: $g / 12.92;\n }\n\n @if $b > 0.04045 {\n $b: pow((($b + 0.055) / 1.055), 2.4);\n } @else {\n $b: $b / 12.92;\n }\n\n $x: ($r * 0.4124564 + $g * 0.3575761 + $b * 0.1804375) / 0.95047;\n $y: ($r * 0.2126729 + $g * 0.7151522 + $b * 0.072175) / 1;\n $z: ($r * 0.0193339 + $g * 0.119192 + $b * 0.9503041) / 1.08883;\n\n // XYZ to LAB\n @if $x > 0.008856 {\n $x: pow($x, 1/3);\n } @else {\n $x: (7.787 * $x) + (16 / 116);\n }\n\n @if $y > 0.008856 {\n $y: pow($y, 1/3);\n } @else {\n $y: (7.787 * $y) + (16 / 116);\n }\n\n @if $z > 0.008856 {\n $z: pow($z, 1/3);\n } @else {\n $z: (7.787 * $z) + (16 / 116);\n }\n\n $l: (116 * $y) - 16;\n $a: 500 * ($x - $y);\n $b: 200 * ($y - $z);\n\n @return ($l, $a, $b);\n}\n\n@function lab-to-rgb($lab) {\n $l: nth($lab, 1);\n $a: nth($lab, 2);\n $b: nth($lab, 3);\n\n $y: ($l + 16) / 116;\n $x: $a / 500 + $y;\n $z: $y - $b / 200;\n\n @if pow($y / 1%, 3) > 0.008856 {\n $y: pow($y / 1%, 3);\n } @else {\n $y: ($y / 1% - 16 / 116) / 7.787;\n }\n\n @if pow($x / 1%, 3) > 0.008856 {\n $x: pow($x / 1%, 3);\n } @else {\n $x: ($x / 1% - 16 / 116) / 7.787;\n }\n\n @if pow($z / 1%, 3) > 0.008856 {\n $z: pow($z / 1%, 3);\n } @else {\n $z: ($z / 1% - 16 / 116) / 7.787;\n }\n\n $x: $x * 0.95047;\n $y: $y * 1;\n $z: $z * 1.08883;\n\n $r: $x * 3.2404542 + $y * -1.5371385 + $z * -0.4985314;\n $g: $x * -0.969266 + $y * 1.8760108 + $z * 0.041556;\n $b: $x * 0.0556434 + $y * -0.2040259 + $z * 1.0572252;\n\n @if $r > 0.0031308 {\n $r: 1.055 * pow($r, (1 / 2.4)) - 0.055;\n } @else {\n $r: 12.92 * $r;\n }\n\n @if $g > 0.0031308 {\n $g: 1.055 * pow($g, (1 / 2.4)) - 0.055;\n } @else {\n $g: 12.92 * $g;\n }\n\n @if $b > 0.0031308 {\n $b: 1.055 * pow($b, (1 / 2.4)) - 0.055;\n } @else {\n $b: 12.92 * $b;\n }\n\n @return rgb($r * 255, $g * 255, $b * 255);\n}","_type":"code","_key":"945dee613d6b"},{"style":"normal","markDefs":[],"children":[{"text":"Second, a helper for calculating the blending at any given position:","marks":[],"_type":"span","_key":"3bbf568f93ef"}],"_type":"block","_key":"c3dbc6c8e90a"},{"language":"scss","code":"@function interpolate-lab($start-color, $end-color, $position) {\n $start-lab: rgb-to-lab($start-color);\n $end-lab: rgb-to-lab($end-color);\n\n $position: $position / 1%;\n\n $l: nth($start-lab, 1) + (nth($end-lab, 1) - nth($start-lab, 1)) * $position;\n $a: nth($start-lab, 2) + (nth($end-lab, 2) - nth($start-lab, 2)) * $position;\n $b: nth($start-lab, 3) + (nth($end-lab, 3) - nth($start-lab, 3)) * $position;\n\n @return lab-to-rgb(($l, $a, $b));\n}","_type":"code","_key":"87944dbabfb0"},{"style":"normal","markDefs":[],"children":[{"text":"Now, we can replace SCSS's ","marks":[],"_type":"span","_key":"2266cd276c5a"},{"text":"mix","marks":["code"],"_type":"span","_key":"b33f374f4e30"},{"text":" with our new ","marks":[],"_type":"span","_key":"a420192ed4e4"},{"text":"interpolate-lab","marks":["code"],"_type":"span","_key":"353b2e9347f3"},{"text":" function:","marks":[],"_type":"span","_key":"c3673d2379fd"}],"_type":"block","_key":"e75e41846915"},{"language":"scss","code":"@function ease-gradient($dir, $color1, $color2) {\n // ...\n $interpolated-color: interpolate-lab($color1, $color2, $eased-percentage);\n // ...\n}","_type":"code","_key":"4226fc9b97bd"},{"style":"normal","markDefs":[],"children":[{"text":"It's important to note that this exact colour mixing implementation won't work with transparency. With some more tweaking, it could, but I didn't go that far since I just wanted interpolation between solid colours. One way might be to calculate the alpha channel's positioning seperately, then recombine it with ","marks":[],"_type":"span","_key":"8d21b83e310f"},{"text":"rgba","marks":["code"],"_type":"span","_key":"9006289898ef"},{"text":" after ","marks":[],"_type":"span","_key":"3b314a6de79a"},{"text":"rgb_to_lab","marks":["code"],"_type":"span","_key":"5fbb1aedbcb0"},{"text":" and vice versa.","marks":[],"_type":"span","_key":"b38a8311fa02"}],"_type":"block","_key":"04035c59cea3"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"f98fc6cf5bcc"}],"_type":"block","_key":"b1ec61357187"},{"style":"h1","markDefs":[],"children":[{"text":"Fin","marks":[],"_type":"span","_key":"90c101d2d217"}],"_type":"block","_key":"cf8f6ead7c36"},{"style":"normal","markDefs":[],"children":[{"text":"And here's the end result, mixed in the LAB space and eased in/out, versus the stock mix and interpolation you'd get from linear-gradient.","marks":[],"_type":"span","_key":"da6c6c836645"}],"_type":"block","_key":"b7b7b524c57e"},{"asset":{"_type":"reference","_ref":"image-3c8114551ae986822f2fb7c896b4ab6ade7c92e3-1589x749-png"},"_type":"image","_key":"bf928a23aa20"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"47897dedd28c"}],"_type":"block","_key":"76c4e286f024"},{"style":"normal","markDefs":[],"children":[{"text":"If you want to have some more fun, try using other easing functions rather than the simple 'ease' or 'ease-in-out' demo'd here – it's fairly simple to achieve some cool effects!","marks":[],"_type":"span","_key":"478223f72fc1"}],"_type":"block","_key":"dbe8c7ebb643"},{"asset":{"_type":"reference","_ref":"image-e4b35cad2c22f6fb1efb978491e25be714979fc2-1589x1829-png"},"_type":"image","_key":"a2ff62df8e24"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"fa97a8a0feb9"}],"_type":"block","_key":"ab2fee02e361"},{"style":"normal","markDefs":[],"children":[{"text":"That's all, though – I hope this info is useful to you in some form! Even ignoring the more-complex LAB space colour mixing, I've found even just using some easing can make a big difference in how gradients look, especially when used as overlays, backgrounds, or in places transparency is needed. Please feel free to reach out if you have any questions about the stuff covered in this post. Happy CSS-ing 🖌️","marks":[],"_type":"span","_key":"5d74ac044b46"}],"_type":"block","_key":"5ea361ff9d38"}],"_type":"post","_rev":"OV3o2t7M68aAVZSgGfj6xl","_id":"8963ed30-98df-493d-9c96-59315b6d35af"},{"views":5153,"title":"Running Linux-only binaries under FreeBSD","tags":[{"title":"Linux","slug":{"current":"linux","_type":"slug"},"_id":"f5ced506-6b69-4557-b4e8-819845089b42"},{"title":"FreeBSD","slug":{"current":"freebsd","_type":"slug"},"_id":"d6b23b2f-baf8-435a-b7a8-4ca7500411e4"},{"title":"System Administration","slug":{"current":"system-administration","_type":"slug"},"_id":"3c3e7e57-80c2-486d-9569-1cf31cc335b5"}],"slug":{"current":"running-linux-binaries-under-freebsd","_type":"slug"},"numberOfCharacters":5466,"headings":[{"typeLevel":2,"children":[],"key":"c6cbaf89c395","text":"Jails & Linux Binary Compatibility","type":"h2","parent":null},{"typeLevel":2,"children":[{"typeLevel":3,"children":[],"key":"0679569c013b","text":"Preparing the service script","type":"h3","parent":"244a3cf93cf6"},{"typeLevel":3,"children":[],"key":"39eadbfb0046","text":"Optional: ZFS dataset","type":"h3","parent":"244a3cf93cf6"},{"typeLevel":3,"children":[],"key":"0aa7adb62bdf","text":"Directory creation","type":"h3","parent":"244a3cf93cf6"},{"typeLevel":3,"children":[],"key":"a85298c2eea5","text":"Starting the service","type":"h3","parent":"244a3cf93cf6"}],"key":"244a3cf93cf6","text":"Getting started","type":"h2","parent":null},{"typeLevel":2,"children":[{"typeLevel":3,"children":[],"key":"5f1653f266a1","text":"Configuration","type":"h3","parent":"0ac1e5ce2ee2"},{"typeLevel":3,"children":[],"key":"f5694ab3ac27","text":"Updating / Installing packages","type":"h3","parent":"0ac1e5ce2ee2"},{"typeLevel":3,"children":[],"key":"b484525b1179","text":"Uninstalling","type":"h3","parent":"0ac1e5ce2ee2"}],"key":"0ac1e5ce2ee2","text":"Bootstrapping Ubuntu Base","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"6870cda8928f","text":"Wrapping up","type":"h2","parent":null}],"estimatedWordCount":1093,"estimatedReadingTime":9,"desc":"Running Linux-only binaries under FreeBSD using its Linux binary compatibility tools and Jails","date":"2024-03-31","body":[{"style":"normal","markDefs":[],"children":[{"text":"I've taken a real liking to ","marks":[],"_type":"span","_key":"9a37ae86da98"},{"text":"FreeBSD","marks":["notranslate"],"_type":"span","_key":"75b14968f6ef"},{"text":" lately, but my biggest initial annoyance was its lack of compatibility with Linux apps and tools I've grown accustomed to. ","marks":[],"_type":"span","_key":"342c57e7f1ac"}],"_type":"block","_key":"78917a4dddba"},{"style":"normal","markDefs":[],"children":[{"text":"Despite also being a Unix-like operating system, it isn't able to run many Linux binaries and programs. Spotify is one example I ran into while testing out ","marks":[],"_type":"span","_key":"7919522adf73"},{"text":"FreeBSD","marks":["notranslate"],"_type":"span","_key":"3a49eb4608b4"},{"text":" as a desktop OS. Due to certain DRM library dependencies (*cough cough*, Widevine CDM), it's not able to run natively. This would be a deal-breaker for me, but luckily, there's a quick and rather easy workaround, using a virtualization concept called Jails, and ","marks":[],"_type":"span","_key":"3030c9b452a3"},{"text":"FreeBSD's","marks":["notranslate"],"_type":"span","_key":"b24f47816455"},{"text":" Linux binary compatibility.","marks":[],"_type":"span","_key":"f89d272b728b"}],"_type":"block","_key":"077fd2cad67d"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"8beab4833521"}],"_type":"block","_key":"f1336494a369"},{"style":"h2","markDefs":[],"children":[{"text":"Jails & Linux Binary Compatibility","marks":[],"_type":"span","_key":"01ce4e9a1821"}],"_type":"block","_key":"c6cbaf89c395"},{"style":"normal","markDefs":[{"note":[{"style":"normal","markDefs":[{"newtab":true,"href":"https://wiki.freebsd.org/Jails","external":true,"_type":"link","_key":"d4882c72398e"}],"children":[{"text":"More on Jails: ","marks":[],"_type":"span","_key":"caff4ecf4e300"},{"text":"https://wiki.freebsd.org/Jails","marks":["d4882c72398e"],"_type":"span","_key":"21164d23eace"}],"_type":"block","_key":"623cb6077342"}],"_type":"footnote","_key":"5d62a98a18df"}],"children":[{"text":"Jails are FreeBSD's approach to OS-level virtualization.","marks":["5d62a98a18df"],"_type":"span","_key":"7de542c1c3c1"},{"text":" Each Jail operates independently with its own file system, network stack, and process tree, and is isolated from the host and from other Jails. With much less overhead than full-blown virtual machines, they're perfect for running a Linux environment efficiently.","marks":[],"_type":"span","_key":"7fddff5baf6f"}],"_type":"block","_key":"8f0e6e568f5b"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"46db0dffb685"}],"_type":"block","_key":"f9e8d81fe962"},{"style":"normal","markDefs":[],"children":[{"text":"FreeBSD's Linux binary compatibility feature is the magic wand here - it emulates a Linux environment within a Jail, allowing you to run many Linux apps seamlessly. The environment I'll be setting up here, based on Ubuntu, provides the necessary libraries and components required to run many Linux-only binaries (not just Spotify, although that's what my focus was on here). Not everything works perfectly, however, and certain binaries or programs may require modifying the basic setup I detail in this article.","marks":[],"_type":"span","_key":"9c7797f46bca"}],"_type":"block","_key":"0fe86101cd33"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"8e04f17808c1"}],"_type":"block","_key":"7a433b854dc3"},{"style":"h2","markDefs":[],"children":[{"text":"Getting started","marks":[],"_type":"span","_key":"b0393de3999c"}],"_type":"block","_key":"244a3cf93cf6"},{"style":"normal","markDefs":[],"children":[{"text":"First, a quick note: throughout this guide, lines starting with ","marks":[],"_type":"span","_key":"b0c1892844e4"},{"text":"$","marks":["code"],"_type":"span","_key":"1a85e423c5f7"},{"text":" relate to our host BSD shell, while ","marks":[],"_type":"span","_key":"7e65f0a0c626"},{"text":"/$","marks":["code"],"_type":"span","_key":"ca68a9523a26"},{"text":" denotes commands to be run within the Jail.","marks":[],"_type":"span","_key":"9015d8aaedf8"}],"_type":"block","_key":"1e8a6ec9c07d"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"838cd5c78033"}],"_type":"block","_key":"14c25e7edb7e"},{"style":"normal","markDefs":[],"children":[{"text":"First things first, let's enable Linux binary compatibility. Loading the necessary kernel modules is the first step:","marks":[],"_type":"span","_key":"511098521611"}],"_type":"block","_key":"b1ed98f1c6a9"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"linux","marks":["code"],"_type":"span","_key":"4644a962f73e"},{"text":": The basic Linux compat layer, necessary for running Linux binaries on FreeBSD","marks":[],"_type":"span","_key":"0e4ef1aa69ab"}],"_type":"block","_key":"6e011337d802"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"linux64","marks":["code"],"_type":"span","_key":"6d3f04c62b74"},{"text":": Specifically for 64-bit compat","marks":[],"_type":"span","_key":"b7430829c1eb"}],"_type":"block","_key":"4cda799e39cd"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"fdescfs","marks":["code"],"_type":"span","_key":"7f926a216731"},{"text":": Used by Linux programs to access file descriptors in a UNIX-like manner","marks":[],"_type":"span","_key":"6f0740845be8"}],"_type":"block","_key":"162e147e5a51"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"linprocfs","marks":["code"],"_type":"span","_key":"5f3d74a8756c"},{"text":": Emulates the Linux ","marks":[],"_type":"span","_key":"11418ec96f8e"},{"text":"/proc","marks":["code"],"_type":"span","_key":"a4aed722c70e"},{"text":" filesystem, providing process and system information in a way Linux binaries will expect","marks":[],"_type":"span","_key":"a961e9622191"}],"_type":"block","_key":"7fbbeb72a9f9"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"tmpfs","marks":["code"],"_type":"span","_key":"02f81415f2a8"},{"text":": A temporary filesystem for creation of cache in RAM","marks":[],"_type":"span","_key":"b441bd9ed52c"}],"_type":"block","_key":"c2f381145521"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"linsysfs","marks":["code"],"_type":"span","_key":"91df159f8504"},{"text":": Emulates the Linux ","marks":[],"_type":"span","_key":"ed4b897e607d"},{"text":"/sys","marks":["code"],"_type":"span","_key":"c8f369adba71"},{"text":" filesystem, providing system and device information for Linux binaries, similar to ","marks":[],"_type":"span","_key":"a22ccf7f5498"},{"text":"linprocfs","marks":["code"],"_type":"span","_key":"8b7ebe64689e"}],"_type":"block","_key":"bbd98e847535"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"93310a60d649"}],"_type":"block","_key":"efb923d5a163"},{"language":"shell","code":"$ kldload linux linux64 fdescfs linprocfs tmpfs linsysfs","_type":"code","_key":"b7b47feedc8c"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"4be052b5c6b6"}],"_type":"block","_key":"4f89e092f8b6"},{"style":"normal","markDefs":[],"children":[{"text":"This can be done manually at run-time but it's easy to persist this change across reboots by adding these all to ","marks":[],"_type":"span","_key":"abf7377f6e5a"},{"text":"/boot/loader.conf","marks":["code"],"_type":"span","_key":"6436eb58637b"},{"text":":","marks":[],"_type":"span","_key":"caa4af60f074"}],"_type":"block","_key":"23ffcb20e0e2"},{"language":"shell","code":"$ echo -e \"linux_load=\\\"YES\\\"\\nlinux64_load=\\\"YES\\\"\\nfdescfs_load=\\\"YES\\\"\\nlinprocfs_load=\\\"YES\\\"\\ntmpfs_load=\\\"YES\\\"\\nlinsysfs_load=\\\"YES\\\"\" >> /boot/loader.conf","_type":"code","_key":"fc1ea06e0eb6"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"69eac4bdd995"}],"_type":"block","_key":"3ede357b750c"},{"style":"h3","markDefs":[],"children":[{"text":"Preparing the service script","marks":[],"_type":"span","_key":"3d431b01852c"}],"_type":"block","_key":"0679569c013b"},{"style":"normal","markDefs":[],"children":[{"text":"Our goal is to keep things (relatively) simple. We'll create a script to manage the Ubuntu Jail, under ","marks":[],"_type":"span","_key":"969a303506f0"},{"text":"/usr/local/etc/rc.d/ubuntu","marks":["code"],"_type":"span","_key":"c81fafb04a4c"},{"text":". It'll handle loading necessary modules and setting up the Jail's environment.","marks":[],"_type":"span","_key":"465f1c6ad0bc"}],"_type":"block","_key":"9cbba9c5b646"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"8cc694a93a42"}],"_type":"block","_key":"fb3cd83a8852"},{"language":"shell","filename":"ubuntu","code":"#!/bin/sh\n\n# PROVIDE: ubuntu\n# REQUIRE: archdep mountlate\n# KEYWORD: nojail\n\n# Import FreeBSD rc.subr scripting infra\n. /etc/rc.subr\n\nname=\"ubuntu\"\ndesc=\"Ubuntu for Linux binary compat\"\nrcvar=\"ubuntu_enable\"\nstart_cmd=\"${name}_start\"\nstop_cmd=\":\"\n\nunmounted() {\n [ `stat -f \"%d\" \"$1\"` == `stat -f \"%d\" \"$1/..\"` -a `stat -f \"%i\" \"$1\"` != `stat -f \"%i\" \"$1/..\"` ]\n}\n\nubuntu_start() {\n local _tmpdir\n\n # Load Linux & Linux64 compat modules\n load_kld -e 'linux(aout|elf)' linux\n if [ `sysctl -n hw.machine_arch` == \"amd64\" ]; then\n load_kld -e 'linux64elf' linux64\n fi\n\n # Update the Linux dynamic linker cache if needed\n if [ -x \"/compat/ubuntu/sbin/ldconfigDisabled\" ]; then\n _tmpdir=`mktemp -d -t linux-ldconfig`\n /compat/ubuntu/sbin/ldconfig -C ${_tmpdir}/ld.so.cache\n if ! cmp -s \"${_tmpdir}/ld.so.cache\" \"/compat/ubuntu/etc/ld.so.cache\"; then\n cat \"${_tmpdir}/ld.so.cache\" > \"/compat/ubuntu/etc/ld.so.cache\"\n fi\n rm -rf ${_tmpdir}\n fi\n\n # Load modules for proper terminal/device support\n load_kld pty\n\n # Set system compatibility brand for executables\n if [ `sysctl -ni kern.elf64.fallback_brand` -eq \"-1\" ]; then\n sysctl kern.elf64.fallback_brand=3 > /dev/null\n fi\n if [ `sysctl -ni kern.elf32.fallback_brand` -eq \"-1\" ]; then\n sysctl kern.elf32.fallback_brand=3 > /dev/null\n fi\n\n # Set the emulation path to the Ubuntu compat layer\n sysctl compat.linux.emul_path=\"/compat/ubuntu\"\n\n # Mount necessary filesystems\n unmounted \"/compat/ubuntu/dev\" && (mount -o nocover -t devfs devfs \"/compat/ubuntu/dev\" || exit 1)\n unmounted \"/compat/ubuntu/dev/fd\" && (mount -o nocover,linrdlnk -t fdescfs fdescfs \"/compat/ubuntu/dev/fd\" || exit 1)\n unmounted \"/compat/ubuntu/dev/shm\" && (mount -o nocover,mode=1777 -t tmpfs tmpfs \"/compat/ubuntu/dev/shm\" || exit 1)\n unmounted \"/compat/ubuntu/home\" && (mount -t nullfs /home \"/compat/ubuntu/home\" || exit 1)\n unmounted \"/compat/ubuntu/proc\" && (mount -o nocover -t linprocfs linprocfs \"/compat/ubuntu/proc\" || exit 1)\n unmounted \"/compat/ubuntu/sys\" && (mount -o nocover -t linsysfs linsysfs \"/compat/ubuntu/sys\" || exit 1)\n unmounted \"/compat/ubuntu/tmp\" && (mount -t nullfs /tmp \"/compat/ubuntu/tmp\" || exit 1)\n\n # Mount devfs, fdescfs, and procfs on the host\n unmounted /dev/fd && (mount -o nocover -t fdescfs fdescfs /dev/fd || exit 1)\n unmounted /proc && (mount -o nocover -t procfs procfs /proc || exit 1)\n true\n}\n\nload_rc_config $name\nrun_rc_command \"$1\"","_type":"code","_key":"60ed1b21c06a"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"3f75aac9b30c"}],"_type":"block","_key":"0ce5bb121b1d"},{"style":"h3","markDefs":[],"children":[{"text":"Optional: ZFS dataset","marks":[],"_type":"span","_key":"f36753d2899a"}],"_type":"block","_key":"39eadbfb0046"},{"style":"normal","markDefs":[],"children":[{"text":"If you want the benefits of ZFS (snapshots, integrity checks, deduplication, etc), now's a good time to create a ZFS dataset for the Ubuntu directory:","marks":[],"_type":"span","_key":"99f815a0a1a2"}],"_type":"block","_key":"4e66c8174db3"},{"language":"shell","code":"$ zfs create -o compression=on -o mountpoint=/compat zroot/compat","_type":"code","_key":"7abd5f37e27a"},{"style":"normal","markDefs":[],"children":[{"text":"You could also use BTRFS - although it's much less battle-tested, it's what I use on my main Arch install, and I chose to use it here as well rather than ZFS.","marks":[],"_type":"span","_key":"3c6375545660"}],"_type":"block","_key":"4c7f19036814"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"d879bbb6b7a3"}],"_type":"block","_key":"1be612ec4d42"},{"style":"normal","markDefs":[],"children":[{"text":"For either option, snapshotting should be used as a quick backup before making any potentially-breaking changes:","marks":[],"_type":"span","_key":"96a5eaf27245"}],"_type":"block","_key":"81401024b02d"},{"language":"shell","code":"$ zfs snapshot -r zroot/compat@2022-12-31","_type":"code","_key":"7210ae570b0f"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"c4dd78883b19"}],"_type":"block","_key":"02203e575535"},{"style":"h3","markDefs":[],"children":[{"text":"Directory creation","marks":[],"_type":"span","_key":"d641fd412dac"}],"_type":"block","_key":"0aa7adb62bdf"},{"style":"normal","markDefs":[],"children":[{"text":"Before diving into installing Ubuntu, we need to ensure the necessary directories are in place:","marks":[],"_type":"span","_key":"7087745f24d6"}],"_type":"block","_key":"06a790996eb0"},{"language":"shell","code":"$ mkdir -p /compat/ubuntu/{dev/fd,dev/shm,home,proc,sys,tmp}","_type":"code","_key":"ee0ffc313173"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"97559d0f449f"}],"_type":"block","_key":"4beebef5857f"},{"style":"h3","markDefs":[],"children":[{"text":"Starting the service","marks":[],"_type":"span","_key":"727c5322c303"}],"_type":"block","_key":"a85298c2eea5"},{"style":"normal","markDefs":[],"children":[{"text":"Now we enable (and start) the service with ","marks":[],"_type":"span","_key":"e7f446a9299c"},{"text":"sysrc","marks":["code"],"_type":"span","_key":"6fab9026d80e"},{"text":":","marks":[],"_type":"span","_key":"93a735635591"}],"_type":"block","_key":"053af4f9f500"},{"language":"shell","code":"$ sysrc ubuntu_enable=YES\n$ service ubuntu start\ncompat.linux-emul_path: /compat/linux -> /compat/ubuntu","_type":"code","_key":"bf343b948707"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"4314bde9ab5b"}],"_type":"block","_key":"4ab2628dd0fc"},{"style":"h2","markDefs":[],"children":[{"text":"Bootstrapping Ubuntu Base","marks":[],"_type":"span","_key":"46e34d56067d"}],"_type":"block","_key":"0ac1e5ce2ee2"},{"style":"normal","markDefs":[{"note":[{"style":"normal","markDefs":[{"newtab":true,"href":"https://docs.freebsd.org/en/books/handbook/linuxemu/#linuxemu-debootstrap","external":true,"_type":"link","_key":"bd4fddb8c05b"}],"children":[{"text":"More on FreeBSD's Debootstrap: ","marks":[],"_type":"span","_key":"e50b3400362f0"},{"text":"https://docs.freebsd.org/en/books/handbook/linuxemu/#linuxemu-debootstrap","marks":["bd4fddb8c05b"],"_type":"span","_key":"fb6c23aed41a"}],"_type":"block","_key":"77eda18e736e"}],"_type":"footnote","_key":"82df0efb09c6"}],"children":[{"text":"Using Debootstrap, we'll download and install the Ubuntu base systems by specifying the target's name, e.g., focal for 'Focal Fossa' (version 20.04 LTS).","marks":["82df0efb09c6"],"_type":"span","_key":"28bca03700bf"}],"_type":"block","_key":"846ed3448f18"},{"language":"shell","code":"$ pkg install debootstrap\n$ debootstrap --arch=amd64 --no-check-gpg focal /compat/ubuntu","_type":"code","_key":"5d5180fe8b0e"},{"style":"normal","markDefs":[],"children":[{"text":"The output should look similar to the following:","marks":[],"_type":"span","_key":"f0bc0ec97947"}],"_type":"block","_key":"f101d63fc4a0"},{"language":"shell","code":"I: Retrieving InRelease\nI: Checking Release signature\nI: Valid Release signature (key id F6ECB3762474EDA9D21B7022871920D1991BC93C)\nI: Retrieving Packages\nI: Validating Packages\nI: Resolving dependencies of required packages...\nI: Resolving dependencies of base packages...\nI: Checking component main on http://archive.ubuntu.com/ubuntu...\n[...]\nI: Configuring console-setup...\nI: Configuring kbd...\nI: Configuring ubuntu-minimal...\nI: Configuring libc-bin...\nI: Configuring ca-certificates...\nI: Base system installed successfully.","_type":"code","_key":"33299abfc1d2"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"041dc8ca9830"}],"_type":"block","_key":"42becfec9c86"},{"style":"normal","markDefs":[],"children":[{"text":"Post-installation, we need to restart the service:","marks":[],"_type":"span","_key":"fefe32c7d129"}],"_type":"block","_key":"f41ad91915ac"},{"language":"shell","code":"$ service ubuntu restart\ncompat.linux.emul_path: /compat/ubuntu -> /compat/ubuntu","_type":"code","_key":"733be734e263"},{"style":"normal","markDefs":[],"children":[{"text":"And replace the following shared lib with a new symbolic link:","marks":[],"_type":"span","_key":"e3bb45ee7dcc"}],"_type":"block","_key":"08d7acda3de8"},{"language":"shell","code":"$ cd /compat/ubuntu/lib64/\n$ rm ./ld-linux-x86-64.so.2 && \\\n ln -s ../lib/x86_64-linux-gnu/ld-2.31.so ld-linux-x86-64.so.2","_type":"code","_key":"884e77f365c0"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"f3d85c1c1154"}],"_type":"block","_key":"23cdeb1f47e4"},{"style":"h3","markDefs":[],"children":[{"text":"Configuration","marks":[],"_type":"span","_key":"71c9a66bf349"}],"_type":"block","_key":"5f1653f266a1"},{"style":"normal","markDefs":[],"children":[{"text":"There are a few small configuration tweaks we need to make. First, though, ","marks":[],"_type":"span","_key":"75d3defb91df"},{"text":"chroot","marks":["notranslate"],"_type":"span","_key":"1263c7a91b70"},{"text":" into the Jail, which will confine the following commands to it:","marks":[],"_type":"span","_key":"4bedc856c74e"}],"_type":"block","_key":"aa0d418803a6"},{"language":"shell","code":"$ chroot /compat/ubuntu /bin/bash","_type":"code","_key":"1c3de9ec7f57"},{"style":"normal","markDefs":[],"children":[{"text":"Next, we can adjust the timezone to match our host system:","marks":[],"_type":"span","_key":"bcd1dfbc8388"}],"_type":"block","_key":"b78e2984c981"},{"language":"shell","code":"/$ printf \"%b\\n\" \"0.0 0 0.0\\n0\\nUTC\" > /etc/adjtime\n/$ dpkg-reconfigure tzdata","_type":"code","_key":"ba61a10c7d00"},{"style":"normal","markDefs":[],"children":[{"text":"Fix the ","marks":[],"_type":"span","_key":"3c8d150afc60"},{"text":"apt","marks":["code"],"_type":"span","_key":"c25db96e5355"},{"text":" package manager:","marks":[],"_type":"span","_key":"7b121283adad"}],"_type":"block","_key":"67e1a8e27516"},{"language":"shell","code":"/$ printf \"APT::Cache-Start 251658240;\" > /etc/apt/apt.conf.d/00aptitude","_type":"code","_key":"6bdf674e49e5"},{"style":"normal","markDefs":[],"children":[{"text":"And add some initial repositories to ","marks":[],"_type":"span","_key":"86b2bc496490"},{"text":"sources.list","marks":["code"],"_type":"span","_key":"cac708e51012"},{"text":":","marks":[],"_type":"span","_key":"29fe0732fbf5"}],"_type":"block","_key":"b59c0c6c624c"},{"language":"shell","code":"/$ printf \"deb http://archive.ubuntu.com/ubuntu/ focal main restricted universe multiverse\" > /etc/apt/sources.list","_type":"code","_key":"f6232ed5973b"},{"style":"normal","markDefs":[],"children":[{"text":"To exit the jail, use ","marks":[],"_type":"span","_key":"8233b6c3b44a"},{"text":"exit","marks":["code"],"_type":"span","_key":"ffe0b070810c"},{"text":".","marks":[],"_type":"span","_key":"17db8dca68f0"}],"_type":"block","_key":"2812c7dd2760"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"8f6ca35e9fbc"}],"_type":"block","_key":"2bf6d6c2570b"},{"style":"normal","markDefs":[],"children":[{"text":"And voilà! FreeBSD is good-to-go now with our Ubuntu compatibility-layer jail, with its Ubuntu base system installed.","marks":[],"_type":"span","_key":"3f11a1123c43"}],"_type":"block","_key":"fc7f41613b34"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"a71c5ef2b84b"}],"_type":"block","_key":"5085d6537177"},{"style":"h3","markDefs":[],"children":[{"text":"Updating / Installing packages","marks":[],"_type":"span","_key":"1889c59219ef"}],"_type":"block","_key":"f5694ab3ac27"},{"style":"normal","markDefs":[],"children":[{"text":"First, make sure you're ","marks":[],"_type":"span","_key":"f34a5ae9c8ea"},{"text":"chroot","marks":["code"],"_type":"span","_key":"47c4d3ad6753"},{"text":"-ed into the ","marks":[],"_type":"span","_key":"db2c5829dd45"},{"text":"Jail","marks":["notranslate"],"_type":"span","_key":"d6d78c80a786"},{"text":". ","marks":[],"_type":"span","_key":"e89a2660957d"},{"text":"apt","marks":["code"],"_type":"span","_key":"2ead951e4cc7"},{"text":" can then be run as it would on a normal Ubuntu system:","marks":[],"_type":"span","_key":"280f976f9cf4"}],"_type":"block","_key":"9996631c210b"},{"language":"shell","code":"$ chroot /compat/ubuntu /bin/bash\n/$ apt update && apt upgrade\n/$ apt autoremove\n/$ apt clean","_type":"code","_key":"40cfaf5c9590"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"1086001f3e72"}],"_type":"block","_key":"37ce48de02da"},{"style":"h3","markDefs":[],"children":[{"text":"Uninstalling","marks":[],"_type":"span","_key":"f5a06a5aae720"}],"_type":"block","_key":"b484525b1179"},{"style":"normal","markDefs":[],"children":[{"text":"If wanted, the Ubuntu ","marks":[],"_type":"span","_key":"ad5e85b7df60"},{"text":"Jail","marks":["notranslate"],"_type":"span","_key":"bfa853b7e355"},{"text":" and these compatibility tools can be safely removed, mostly by following the reverse order. First, the automatic startup we set needs to be disabled. ","marks":[],"_type":"span","_key":"adb819cc5ae2"},{"text":"FreeBSD","marks":["notranslate"],"_type":"span","_key":"e6ef162ff44c"},{"text":" then needs to be rebooted, before finally deleting the Ubuntu system directory and/or destroying its volume.","marks":[],"_type":"span","_key":"a0edad6d6718"}],"_type":"block","_key":"0bbfcaf588a0"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"bd222d935983"}],"_type":"block","_key":"0126793caf36"},{"style":"h2","markDefs":[],"children":[{"text":"Wrapping up","marks":[],"_type":"span","_key":"1f354c7785bc"}],"_type":"block","_key":"6870cda8928f"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://docs.freebsd.org/en/books/handbook/linuxemu/#linuxemu-libs-manually","external":true,"_type":"link","_key":"8d3b32d35f74"}],"children":[{"text":"With those updating/future removal tips in mind, we're almost done! The final step is to use Ubuntu's ","marks":[],"_type":"span","_key":"0da916cce146"},{"text":"apt","marks":["code"],"_type":"span","_key":"b23af0ed776e"},{"text":" package manager as you would in a normal Ubuntu system to install Spotify. You may want to create a script or symlink for easier access without needing to navigate the command-line and chroot into the jail each time. That aside, most programs/binaries should work out-of-the-box. If some libraries are still missing, though, there's a section in FreeBSD's docs on ","marks":[],"_type":"span","_key":"29e96627c6a7"},{"text":"installing additional libs manually","marks":["8d3b32d35f74"],"_type":"span","_key":"b9dbe27e8f40"},{"text":".","marks":[],"_type":"span","_key":"951e548bf854"}],"_type":"block","_key":"fb0d9155a92a"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"0d574a8f88ef"}],"_type":"block","_key":"9a3cadd6ba28"},{"asset":{"_type":"reference","_ref":"image-1a1d7128b08b612f4dc8f6858828c168649d178a-1285x721-png"},"_type":"image","_key":"16443d1218bc"},{"style":"normal","markDefs":[],"children":[{"text":"Great success! 🥳","marks":[],"_type":"span","_key":"090e80fe552a"}],"_type":"block","_key":"af3ba8789e99"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"25bf63953f9c"}],"_type":"block","_key":"cc4c867245b5"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://www.micski.dk/2021/12/21/install-ubuntu-base-system-into-freebsds-linux-binary-compatibility/","external":true,"_type":"link","_key":"fa47510989ef"}],"children":[{"text":"I hope this writeup helped out! A massive thanks to Micski and ","marks":[],"_type":"span","_key":"0e4bf6768a4e"},{"text":"their amazing writeup","marks":["fa47510989ef"],"_type":"span","_key":"dbc1980800eb"},{"text":" on this same topic back in 2021 - their steps & scripts are what I based this guide on, and helped me get up-and-running with Spotify, Slack, Zoom, and other essentials, allowing me to daily-drive ","marks":[],"_type":"span","_key":"e47f489a1b92"},{"text":"FreeBSD","marks":["notranslate"],"_type":"span","_key":"70e1eaaa7b22"},{"text":" on my development machine.","marks":[],"_type":"span","_key":"cfed2dfd22e3"}],"_type":"block","_key":"e1b3b9ae7d98"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"0d16d4339e25"}],"_type":"block","_key":"51a758efc4bd"}],"_type":"post","_rev":"BRxxHYbvnOye3Rn7rEtpR5","_id":"37f21991-e4eb-49ac-a255-69223e09166a"},{"views":4489,"title":"Embracing Modern Data Validation in EmberJS","tags":[{"title":"EmberJS","slug":{"current":"ember-js","_type":"slug"},"_id":"28ed727f-58da-424b-8bbb-7e45856ac7f4"},{"title":"Typescript","slug":{"current":"typescript","_type":"slug"},"_id":"f12e4792-7b17-4130-8eb5-dd09d2477241"},{"title":"Web Development","slug":{"current":"web-development","_type":"slug"},"_id":"3078b0c1-7c5e-4759-8bb3-5937fd09208b"},{"title":"Development","slug":{"current":"development","_type":"slug"},"_id":"bc76970a-0753-407f-bfd6-04ec334fdefb"},{"title":"Guides","slug":{"current":"guides","_type":"slug"},"_id":"4501a332-2a0c-4baf-8281-bf59862a250d"}],"slug":{"current":"embracing-modern-data-validation-in-emberjs","_type":"slug"},"numberOfCharacters":9587,"headings":[{"typeLevel":1,"children":[{"typeLevel":2,"children":[],"key":"ea2169c1da38","text":"The Why: So Long, Computed Properties","type":"h2","parent":"b26480c762a3"}],"key":"b26480c762a3","text":"Introduction","type":"h1","parent":null},{"typeLevel":1,"children":[{"typeLevel":3,"children":[],"key":"a504b2acfb0f","text":"The Options","type":"h3","parent":"ab907885792f"},{"typeLevel":3,"children":[],"key":"dc6b40e520e9","text":"Why 'Yup'?","type":"h3","parent":"ab907885792f"}],"key":"ab907885792f","text":"Choosing a Library","type":"h1","parent":null},{"typeLevel":1,"children":[{"typeLevel":3,"children":[],"key":"4aef213eaafb","text":"Class Blueprint","type":"h3","parent":"e322387c9c7a"},{"typeLevel":3,"children":[],"key":"b0c25f302623","text":"Tracking Validation State","type":"h3","parent":"e322387c9c7a"},{"typeLevel":3,"children":[],"key":"24ac1e44c7ac","text":"Typed Validation Results","type":"h3","parent":"e322387c9c7a"},{"typeLevel":3,"children":[],"key":"f49eda516b81","text":"Validating Data","type":"h3","parent":"e322387c9c7a"}],"key":"e322387c9c7a","text":"Implementing the Utility","type":"h1","parent":null},{"typeLevel":1,"children":[],"key":"4915da34fb26","text":"Putting it All Together: Usage Example","type":"h1","parent":null},{"typeLevel":1,"children":[],"key":"13712c68781f","text":"Wrapping Up","type":"h1","parent":null}],"estimatedWordCount":1917,"estimatedReadingTime":16,"desc":"With Ember's shift away from Mixins and Computed Properties towards more standard JavaScript syntax and patterns, I wanted to detail how I wrote a new utility for validating Models, leveraging TypeScript, yup, and Tracked properties in order to leave behind old patterns and provide strict type-safety","date":"2023-09-23","body":[{"style":"h1","markDefs":[],"children":[{"text":"Introduction","marks":[],"_type":"span","_key":"ffd2714d9978"}],"_type":"block","_key":"b26480c762a3"},{"style":"normal","markDefs":[],"children":[{"text":"In an EmberJS codebase I've been working with, Computed Properties and Mixins were previously used to handle Model validations, via ","marks":[],"_type":"span","_key":"79aa391ba1fa0"},{"text":"ember-cp-validations","marks":["code"],"_type":"span","_key":"796fa8a66132"},{"text":". With Ember's shift away from Mixins and Computed Properties towards more standard JavaScript syntax and patterns, I wanted to detail how I wrote a new utility for validating Models, leveraging TypeScript, ","marks":[],"_type":"span","_key":"751fa54b3058"},{"text":"yup","marks":["code"],"_type":"span","_key":"5053b67143c9"},{"text":", and Tracked properties in order to leave behind these old patterns and provide stricter type safety.","marks":[],"_type":"span","_key":"c2e92382da44"}],"_type":"block","_key":"d8ee96c00059"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"9ec86e1b5b00"}],"_type":"block","_key":"65ea832a180b"},{"style":"h2","markDefs":[],"children":[{"text":"The Why: So Long, Computed Properties","marks":[],"_type":"span","_key":"b8a97ded77450"}],"_type":"block","_key":"ea2169c1da38"},{"style":"normal","markDefs":[],"children":[{"text":"Computed Properties have long been a staple in Ember, serving as a mechanism for defining reactive properties based on dependencies. They rely on explicit annotations to list dependencies, which has the tradeoff of making the code more verbose and less intuitive when compared to modern JavaScript patterns.","marks":[],"_type":"span","_key":"6006eb06afb30"}],"_type":"block","_key":"eaa834b67880"},{"language":"javascript","code":"import EmberObject, { computed } from '@ember/object';\n\nexport default class Image extends EmberObject {\n width;\n height;\n\n @computed('width', 'height')\n get aspectRatio() {\n return this.get('width') / this.get('height');\n }\n}","_type":"code","_key":"23036f45b21f"},{"style":"normal","markDefs":[],"children":[{"text":"With that basic example in mind, our previous validation paradigm worked as follows: ","marks":[],"_type":"span","_key":"c3750c60f23f0"},{"text":"buildValidations","marks":["code"],"_type":"span","_key":"811693ba1dfa"},{"text":" is called, provided with an object whose keys relate to property names on the Model to be validated, with their values being the result of calling the ","marks":[],"_type":"span","_key":"bee770a1ff06"},{"text":"validator","marks":["code"],"_type":"span","_key":"efa25de99794"},{"text":" function - given a string representing the validator's name, and provided options, it returns a Computed Property dependent on the Model key in question. The returned result from ","marks":[],"_type":"span","_key":"a9174026e5cd"},{"text":"buildValidations","marks":["code"],"_type":"span","_key":"b2faf3144920"},{"text":" is an EmberObject Mixin, which can then be extended by the Model class to be validated:","marks":[],"_type":"span","_key":"3c988b20aea7"}],"_type":"block","_key":"68e9f336eb48"},{"language":"javascript","code":"import Model from '@ember-data/model';\nimport { buildValidations, validator } from 'ember-cp-validations';\n\nconst Validations = buildValidations({\n someString: [\n validator('presence', {\n presence: true,\n ignoreBlank: true,\n message: 'Enter a string'\n }),\n validator('length', {\n max: 255,\n message: 'String cannot exceed 255 characters'\n })\n ],\n someNumber: validator('presence', {\n presence: true,\n message: 'Enter a number'\n })\n});\n\nexport default class SomeModel extends Model.extend(Validations) {...}","_type":"code","_key":"4e1d7c1b3f35"},{"style":"normal","markDefs":[],"children":[{"text":"Ember's shift away from Computed Properties and several other Ember Classic patterns, including Mixins, left us in an interesting spot. These Classic patterns aren't ","marks":[],"_type":"span","_key":"96c7d29af605"},{"text":"technically","marks":["em"],"_type":"span","_key":"51c5d648cf96"},{"text":" deprecated, but it's safe to say they will be soon, and their usage is discouraged. And that notwithstanding, they don't function quite right with Typescript - They work, but are difficult to use in otherwise-strictly-typed contexts and have issues when using Tracked primitives as dependant keys. ","marks":[],"_type":"span","_key":"82244f1b5357"}],"_type":"block","_key":"9fa5137f87eb"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"201c6756b498"}],"_type":"block","_key":"675599aa2e89"},{"style":"normal","markDefs":[],"children":[{"text":"So how do Tracked properties come into this? As a modern replacement for Computed Properties, they simplify state management and address some flaws of Computed Properties. By annotating a property with the ","marks":[],"_type":"span","_key":"f049a78b155b"},{"text":"@tracked","marks":["code"],"_type":"span","_key":"c3750c60f23f1"},{"text":" decorator, Ember is informed that this particular field is likely to change over time and should trigger any dependent computations when it does. The result is a more straightforward, more explicit, less boilerplate-heavy approach to reactive state management.","marks":[],"_type":"span","_key":"cce86a00ec2e"}],"_type":"block","_key":"46de90c6dfb4"},{"language":"typescript","code":"import { tracked } from '@glimmer/tracking';\n\nclass Image {\n @tracked width: number;\n @tracked height: number;\n\n get aspectRatio() {\n return this.width / this.height;\n }\n\n // ...\n}","_type":"code","_key":"6d92331a246c"},{"style":"normal","markDefs":[{"note":[{"style":"normal","markDefs":[{"newtab":true,"href":"https://api.emberjs.com/ember/5.3/functions/@glimmer%2Ftracking/cached","external":true,"_type":"link","_key":"4166cc97324d"}],"children":[{"text":"https://api.emberjs.com/ember/5.3/functions/@glimmer%2Ftracking/cached","marks":["4166cc97324d"],"_type":"span","_key":"7c05d99087110"}],"_type":"block","_key":"3a6c561b894a"}],"_type":"footnote","_key":"c21d9a3ed7c8"}],"children":[{"text":"A caveat is that Computed Properties also handled caching - native JavaScript getters recompute on each access, which usually isn't ideal. The ","marks":["c21d9a3ed7c8"],"_type":"span","_key":"b22ec29502ff0"},{"text":"@cached","marks":["c21d9a3ed7c8","code"],"_type":"span","_key":"b5ca4cd0ab0c"},{"text":" decorator from ","marks":["c21d9a3ed7c8"],"_type":"span","_key":"52619d838c39"},{"text":"@glimmer/tracking","marks":["c21d9a3ed7c8","code"],"_type":"span","_key":"9886bdac6b27"},{"text":" can be used to cache the getter's value and avoid unnecessary recomputation.","marks":["c21d9a3ed7c8"],"_type":"span","_key":"4991d2b5ba6b"}],"_type":"block","_key":"51474452acbe"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"ab8c68d617e5"}],"_type":"block","_key":"ed9477eb1067"},{"style":"normal","markDefs":[],"children":[{"text":"Moving away from Computed Properties also enables use of standard JavaScript syntax for property assignment and access, instead of EmberObject's ","marks":[],"_type":"span","_key":"23ee176d4930"},{"text":".get()","marks":["code"],"_type":"span","_key":"27daa8d36985"},{"text":"/","marks":[],"_type":"span","_key":"ce6378825845"},{"text":".set()","marks":["code"],"_type":"span","_key":"b22ec29502ff1"},{"text":" methods (mostly - the utility versions of these methods are still useful in some cases), and aligning classes more closely with native JavaScript patterns. Additionally, with Computed Properties, any property could theoretically be observed, potentially leading to unintended external dependencies or excessive re-computations. Tracked properties require explicit annotation, clearly delineating what properties are meant to be observed and reacted upon.","marks":[],"_type":"span","_key":"b22ec29502ff2"}],"_type":"block","_key":"e035810aaed5"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"7e19d4adace5"}],"_type":"block","_key":"870b8097e01a"},{"style":"normal","markDefs":[],"children":[{"text":"All that to say - there's many benefits from this switch ✨","marks":[],"_type":"span","_key":"aa2c0d9d6a2a"}],"_type":"block","_key":"12de8f53ea5e"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"356c198ff458"}],"_type":"block","_key":"1a4c630a7c0e"},{"style":"h1","markDefs":[],"children":[{"text":"Choosing a Library","marks":[],"_type":"span","_key":"9bf5685e51610"}],"_type":"block","_key":"ab907885792f"},{"style":"h3","markDefs":[],"children":[{"text":"The Options","marks":[],"_type":"span","_key":"953d860f31fd0"}],"_type":"block","_key":"a504b2acfb0f"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://github.com/colinhacks/zod","external":true,"_type":"link","_key":"c28954141ff1"},{"newtab":true,"href":"https://github.com/gcanti/io-ts","external":true,"_type":"link","_key":"f42e9d889cd9"},{"newtab":true,"href":"https://github.com/jquense/yup","external":true,"_type":"link","_key":"565db3bd0e7d"}],"children":[{"text":"Data validation libraries in the JavaScript and TypeScript ecosystem are abundant, catering to different paradigms, use-cases, and design philosophies. When it comes to type-safe validation for TypeScript specifically, there were several names I ended up looking into — ","marks":[],"_type":"span","_key":"2bdd04aa73e50"},{"text":"zod","marks":["c28954141ff1","code"],"_type":"span","_key":"e8f30d79d809"},{"text":", ","marks":[],"_type":"span","_key":"0b8166c627c2"},{"text":"io-ts","marks":["f42e9d889cd9","code"],"_type":"span","_key":"415c26bdb21c"},{"text":", and ","marks":[],"_type":"span","_key":"f457206a6f38"},{"text":"yup","marks":["565db3bd0e7d","code"],"_type":"span","_key":"5e0d533491a0"},{"text":". ","marks":[],"_type":"span","_key":"64da5d5d6d6e"}],"_type":"block","_key":"6d7cc94b8622"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"zod","marks":["strong","notranslate"],"_type":"span","_key":"0b351a4083320"},{"text":": Known for robustness and its rich feature set, ","marks":[],"_type":"span","_key":"0b351a4083321"},{"text":"zod","marks":["code"],"_type":"span","_key":"fbd7253257b5"},{"text":" excels in static type inference and allows for the use of Union and Intersection types.","marks":[],"_type":"span","_key":"f063116b3b50"}],"_type":"block","_key":"77e501b19c53"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"io-ts","marks":["strong","notranslate"],"_type":"span","_key":"6a85a46036fc0"},{"text":": Originating from the functional programming world, ","marks":[],"_type":"span","_key":"6a85a46036fc1"},{"text":"io-ts","marks":["code"],"_type":"span","_key":"d8d2368913b0"},{"text":" offers an extremely type-safe validation mechanism. The library is based in functional programming paradigms.","marks":[],"_type":"span","_key":"367091e88bfe"}],"_type":"block","_key":"699b12a57747"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"yup","marks":["strong","notranslate"],"_type":"span","_key":"5e7bf85943c80"},{"text":": Originally created for use in JavaScript, ","marks":[],"_type":"span","_key":"5e7bf85943c81"},{"text":"yup","marks":["code"],"_type":"span","_key":"010720809b8d"},{"text":" was later refactored to TypeScript. It offers good ease-of-use and relatively strong TypeScript support, albeit with some limitations in type inference and missing schema functionality.","marks":[],"_type":"span","_key":"829dda5e56e3"}],"_type":"block","_key":"38012a99e058"},{"style":"normal","markDefs":[],"children":[{"text":"Some other libraries focusing more on input validation are:","marks":[],"_type":"span","_key":"88d4e6b06e0c0"}],"_type":"block","_key":"77b7d640a8ff"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"validator.js","marks":["strong","notranslate"],"_type":"span","_key":"82793b02052d0"},{"text":": Great for simple, string-based validations, i.e. for form inputs, but it lacks the rich feature set and type safety required for more complex data structures.","marks":[],"_type":"span","_key":"82793b02052d1"}],"_type":"block","_key":"44c67dd4af32"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"Joi","marks":["strong","notranslate"],"_type":"span","_key":"991130ad72630"},{"text":": Initially built for Hapi.js but usable standalone, ","marks":[],"_type":"span","_key":"991130ad72631"},{"text":"Joi","marks":["code"],"_type":"span","_key":"66a6dd258499"},{"text":" is another popular validation library. It's highly extensible but, like ","marks":[],"_type":"span","_key":"b0c0c976bc09"},{"text":"validator.js","marks":["code"],"_type":"span","_key":"baf4bf600f1a"},{"text":", less focused on type safety and more verbose compared to ","marks":[],"_type":"span","_key":"487d6bd7b64e"},{"text":"yup","marks":["code"],"_type":"span","_key":"b1a599cd4808"},{"text":" or ","marks":[],"_type":"span","_key":"b3f2baa9de5e"},{"text":"zod","marks":["code"],"_type":"span","_key":"9a1394c04bde"},{"text":".","marks":[],"_type":"span","_key":"bdae7f513492"}],"_type":"block","_key":"5e2d9ce937fe"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"class-validator","marks":["strong","notranslate"],"_type":"span","_key":"1f520a2ae2fb0"},{"text":": Works with TypeScript classes using decorators for validation logic. While tightly integrated with TypeScript, it couples validation logic directly with data models, which wasn't ideal for me.","marks":[],"_type":"span","_key":"1f520a2ae2fb1"}],"_type":"block","_key":"2d1ccf3d5f4f"},{"style":"normal","markDefs":[],"children":[{"text":"There's also an entirely different class of libraries, like ","marks":[],"_type":"span","_key":"4d1e233697930"},{"text":"VeeValidate","marks":["code"],"_type":"span","_key":"8f634dfdfdb8"},{"text":" and ","marks":[],"_type":"span","_key":"d82faad4b873"},{"text":"react-hook-form","marks":["code"],"_type":"span","_key":"2174b2902517"},{"text":" which are framework-specific and concentrate on form validation. These can be useful for front-end validation for their respective UI library, but they don't offer the same flexibility as ","marks":[],"_type":"span","_key":"8975196aedc3"},{"text":"yup","marks":["code"],"_type":"span","_key":"329b33543482"},{"text":" or ","marks":[],"_type":"span","_key":"12618d7c9419"},{"text":"zod","marks":["code"],"_type":"span","_key":"ef72a13c1f49"},{"text":" when it comes to validating arbitrary data structures, nor do they usually offer type safety to the same degree.","marks":[],"_type":"span","_key":"ae59e757abcf"}],"_type":"block","_key":"af1899fa7923"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"9350a3e7b9cc"}],"_type":"block","_key":"9fd2340c0761"},{"style":"h3","markDefs":[],"children":[{"text":"Why 'Yup'?","marks":[],"_type":"span","_key":"8e0560be38400"}],"_type":"block","_key":"dc6b40e520e9"},{"style":"normal","markDefs":[],"children":[{"text":"So why ","marks":[],"_type":"span","_key":"6372de897b580"},{"text":"yup","marks":["code"],"_type":"span","_key":"9346a72f55a4"},{"text":" over the other libraries mentioned? A few factors: First, it offers a level of simplicity that makes introducing it to other developers on the team much easier. Its syntax is intuitive, and it provides pretty comprehensive documentation. Second, although it was initially developed for JavaScript, its TypeScript support has greatly matured over the years. Its type inference may not be perfect (that honour's given to ","marks":[],"_type":"span","_key":"cdf4ecfc25fc"},{"text":"zod","marks":["code"],"_type":"span","_key":"e9e23d33da90"},{"text":"), but it's more than sufficient for most use-cases. Third, ","marks":[],"_type":"span","_key":"8998aabc7bf9"},{"text":"yup","marks":["code"],"_type":"span","_key":"3fbc7fd40147"},{"text":" provides a high degree of flexibility, allowing for the validation of various data structures, not just form inputs or DOM elements.","marks":[],"_type":"span","_key":"2dd5bd4ea3f1"}],"_type":"block","_key":"1512a26c91f9"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"aa0faf7e1827"}],"_type":"block","_key":"89dfb65af694"},{"style":"normal","markDefs":[],"children":[{"text":"yup","marks":["code"],"_type":"span","_key":"218df4445281"},{"text":" stood out as a balanced choice for my use-case. It allows for easy schema definitions and validations, offers a fair level of type inference, and most importantly, doesn't require adopting a radically different programming paradigm. It is worth acknowledging its main shortcoming: schema type inference inaccuracies. Its type inference indicates that object properties are mandatory, when in actuality they're optional. In my opinion? The overall simplicity and developer experience offered outweighs this limitation. If you want truly strict & precise types, then ","marks":[],"_type":"span","_key":"0f63296b36ab"},{"text":"zod","marks":["code"],"_type":"span","_key":"f5f0681f9f7f"},{"text":" or ","marks":[],"_type":"span","_key":"97251c990c11"},{"text":"io-ts","marks":["code"],"_type":"span","_key":"91dcfb05cb3e"},{"text":" may be more compelling options.","marks":[],"_type":"span","_key":"3c557605d2f3"}],"_type":"block","_key":"bea970c49bbf"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"df3b02429711"}],"_type":"block","_key":"0a26a704ef3e"},{"style":"h1","markDefs":[],"children":[{"text":"Implementing the Utility","marks":[],"_type":"span","_key":"db815798807d0"}],"_type":"block","_key":"e322387c9c7a"},{"style":"normal","markDefs":[],"children":[{"text":"My objective was to offer type-safe validations for Models (or any other objects/classes, really), similar enough in structure to what ","marks":[],"_type":"span","_key":"ec723747ab620"},{"text":"ember-cp-validations","marks":["code"],"_type":"span","_key":"349f485e01e8"},{"text":" provided in order to reduce refactoring work. Besides switching out validation schema and Mixins in Models, I wanted it to be (more or less) a \"drop-in\" replacement.","marks":[],"_type":"span","_key":"707ba8c18266"}],"_type":"block","_key":"c75602eddd11"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"fe953ce9ac54"}],"_type":"block","_key":"9c354fc3f0d1"},{"style":"h3","markDefs":[],"children":[{"text":"Class Blueprint","marks":[],"_type":"span","_key":"fbc9cc3982b90"}],"_type":"block","_key":"4aef213eaafb"},{"style":"normal","markDefs":[],"children":[{"text":"The ","marks":[],"_type":"span","_key":"1affa480e5380"},{"text":"YupValidations","marks":["code"],"_type":"span","_key":"1affa480e5381"},{"text":" class takes in two type parameters, ","marks":[],"_type":"span","_key":"1affa480e5382"},{"text":"T extends FrameworkObject","marks":["code"],"_type":"span","_key":"1affa480e5383"},{"text":", representing the context where validation happens (often, this will be an EmberData Model), and ","marks":[],"_type":"span","_key":"1affa480e5384"},{"text":"S extends ObjectShape","marks":["code"],"_type":"span","_key":"1affa480e5385"},{"text":", representing a base ","marks":[],"_type":"span","_key":"1affa480e5386"},{"text":"yup","marks":["code"],"_type":"span","_key":"512e98da59ad"},{"text":" schema of an empty object. On instantiation, the class takes the calling context and the schema shape to be used, initializing the schema with ","marks":[],"_type":"span","_key":"44e01565af2a"},{"text":"yup.object().shape()","marks":["code"],"_type":"span","_key":"994956724915"},{"text":":","marks":[],"_type":"span","_key":"f2b68579379b"}],"_type":"block","_key":"45da30d49587"},{"language":"typescript","code":"export default class YupValidations {\n context: T;\n shape: S;\n schema: SchemaType;\n\n constructor(context: T, shape: S) {\n this.context = context;\n this.shape = shape;\n this.schema = object().shape(shape); // => SchemaType\n\n const owner = getOwner(context);\n\n if (!owner) {\n Logger.error('YupValidations requires a FrameworkObject context with an owner. Got:', { context });\n } else {\n // Use setOwner to associate the Validator instance as a DestroyableChild\n setOwner(this, owner);\n }\n }\n\n // ...\n}","_type":"code","_key":"d72aa67a173f"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"87a301c56b81"}],"_type":"block","_key":"fe06829ef0a6"},{"style":"h3","markDefs":[],"children":[{"text":"Tracking Validation State","marks":[],"_type":"span","_key":"bc039e79faae0"}],"_type":"block","_key":"b0c25f302623"},{"style":"normal","markDefs":[],"children":[{"text":"The ","marks":[],"_type":"span","_key":"a4e09d3c2a9c0"},{"text":"@tracked","marks":["code"],"_type":"span","_key":"a4e09d3c2a9c1"},{"text":" decorator is used in the class to track any current validation errors. ","marks":[],"_type":"span","_key":"a4e09d3c2a9c2"},{"text":"TrackedObject","marks":["code"],"_type":"span","_key":"2a8be0eb7457"},{"text":" (from ","marks":[],"_type":"span","_key":"070cfde771d4"},{"text":"tracked-built-ins","marks":["code"],"_type":"span","_key":"e7f6dae591c4"},{"text":") is needed for the validation state, since Glimmer's ","marks":[],"_type":"span","_key":"19c747715cf9"},{"text":"@tracked","marks":["code"],"_type":"span","_key":"f578feab88f3"},{"text":" decorator doesn't deep-track objects. This ensures any components accessing validations re-render when the validations change or are re-run.","marks":[],"_type":"span","_key":"2d4415d1dee2"}],"_type":"block","_key":"82a4bf83de5c"},{"language":"typescript","code":"validations: ValidationResult = new TrackedObject({\n isValid: true,\n attrs: {} as ValidationResult['attrs']\n});\n\n@tracked error: ValidationError | null = null;","_type":"code","_key":"ee99f6e072cd"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"1c32b4e7992b"}],"_type":"block","_key":"2309fbc10590"},{"style":"h3","markDefs":[],"children":[{"text":"Typed Validation Results","marks":[],"_type":"span","_key":"886a19147f450"}],"_type":"block","_key":"24ac1e44c7ac"},{"style":"normal","markDefs":[],"children":[{"text":"The class employs some utility types to type validation results based on the schema shape. ","marks":[],"_type":"span","_key":"bb5aa56e42ac0"},{"text":"FieldErrors","marks":["code"],"_type":"span","_key":"bb5aa56e42ac1"},{"text":" creates a mapping from each schema field to its validation messages, validity, and current/previous value. ","marks":[],"_type":"span","_key":"bb5aa56e42ac2"},{"text":"SchemaType","marks":["code"],"_type":"span","_key":"9da38ae1a252"},{"text":" represents the shape of the given schema, and ","marks":[],"_type":"span","_key":"37b512eb4645"},{"text":"ValidationResult","marks":["code"],"_type":"span","_key":"2da97f542bb0"},{"text":" represents the returned validation result.","marks":[],"_type":"span","_key":"5158f54f524f"}],"_type":"block","_key":"d0f8e44fd737"},{"language":"typescript","code":"type _ = T extends {}\n ? {\n [k in keyof T]: T[k];\n }\n : T;\n\ntype SchemaType = ObjectSchema<\n _<{} & TypeFromShape>,\n T,\n _<{} & DefaultFromShape>,\n ''\n>;\n\ntype FieldErrors = {\n [key in keyof InferType]: {\n messages: string[];\n isValid: boolean;\n value?: InferType[key];\n previousValue?: InferType[key];\n };\n};\n\ntype ValidationResult = {\n isValid: boolean;\n attrs: FieldErrors>;\n};","_type":"code","_key":"956ba3e71996"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"0cacfadeacde"}],"_type":"block","_key":"8dce9610522e"},{"style":"h3","markDefs":[],"children":[{"text":"Validating Data","marks":[],"_type":"span","_key":"7ef9ba9e90360"}],"_type":"block","_key":"f49eda516b81"},{"style":"normal","markDefs":[],"children":[{"text":"The ","marks":[],"_type":"span","_key":"690ca97ee16c0"},{"text":"validate","marks":["code"],"_type":"span","_key":"690ca97ee16c1"},{"text":" method triggers validations. It validates all context properties and updates the tracked ","marks":[],"_type":"span","_key":"690ca97ee16c2"},{"text":"validations","marks":["code"],"_type":"span","_key":"690ca97ee16c3"},{"text":" property.","marks":[],"_type":"span","_key":"690ca97ee16c4"}],"_type":"block","_key":"aff84fa3f2da"},{"language":"typescript","code":"#validate = async () => {\n try {\n await this.schema.validate(this.#validationProperties, {\n strict: true,\n abortEarly: false,\n recursive: true,\n context: this.context\n });\n\n this.error = null;\n return { isValid: true, attrs: this.fieldErrors };\n } catch (e) {\n if (!(e as ValidationError)?.inner) {\n this.error = null;\n Logger.error('Encountered an unknown error while validating:', e);\n } else {\n this.error = e as ValidationError;\n }\n return { isValid: false, attrs: this.fieldErrors };\n }\n};\n\nvalidate = async () => {\n const validations = await this.#validate();\n\n this.validations.isValid = validations.isValid;\n this.validations.attrs = validations.attrs;\n\n return validations;\n};\n","_type":"code","_key":"8209054c907f"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"44994edb014e"}],"_type":"block","_key":"0ef541031d5d"},{"style":"normal","markDefs":[],"children":[{"text":"fieldErrors","marks":["code"],"_type":"span","_key":"40865a412031"},{"text":" is a getter which simply presents any existing ","marks":[],"_type":"span","_key":"d3493afd38c2"},{"text":"ValidationError","marks":["code"],"_type":"span","_key":"634b653a54fd"},{"text":"s in a more manageable shape. Likewise for ","marks":[],"_type":"span","_key":"c1fe7bf581e1"},{"text":"#validationProperties","marks":["code"],"_type":"span","_key":"eeaaa9c642a9"},{"text":".","marks":[],"_type":"span","_key":"5dbd83fd9483"}],"_type":"block","_key":"f817bc2a499d"},{"language":"typescript","code":"@cached\nget fieldErrors() {\n const initialValue = Object.keys(this.shape).reduce(\n (acc, key) => {\n acc[key] = { messages: [], isValid: true, value: undefined, originalValue: undefined };\n return acc;\n },\n {} as FieldErrors\n );\n\n return (this.error?.inner ?? []).reduce((acc, validationError) => {\n const key = validationError?.params?.path as string | undefined;\n\n if (!key) {\n return acc;\n }\n\n if (!acc[key]?.messages) {\n acc[key] = { messages: [validationError.message] };\n } else {\n acc[key]!.messages.push(validationError.message);\n }\n\n acc[key].isValid = false;\n acc[key].value = validationError.params?.value;\n acc[key].previousValue = validationError.params?.originalValue;\n\n return acc;\n }, initialValue);\n}\n\nget #validationProperties() {\n return Object.keys(this.shape).reduce(\n (acc, key) => {\n acc[key] = get(this.context, key);\n return acc;\n },\n {} as { [key in keyof InferType]: InferType[key] }\n );\n}","_type":"code","_key":"25ee5a2d86dd"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"30a040a7a663"}],"_type":"block","_key":"e93b99db5f28"},{"style":"h1","markDefs":[],"children":[{"text":"Putting it All Together: Usage Example","marks":[],"_type":"span","_key":"74cefe26675b0"}],"_type":"block","_key":"4915da34fb26"},{"style":"normal","markDefs":[],"children":[{"text":"Now that we've looked at the internals of the utility, here's an example of it in action - suppose you have a Route where you're dealing with an instance of ","marks":[],"_type":"span","_key":"fb55d354c6370"},{"text":"MyModel","marks":["code"],"_type":"span","_key":"733ad0ed81611"},{"text":" and want to validate it before persisting any changes.","marks":[],"_type":"span","_key":"733ad0ed81612"}],"_type":"block","_key":"50f9db26aac8"},{"style":"normal","markDefs":[],"children":[{"text":"First, the model in question:","marks":[],"_type":"span","_key":"fd12fd7a61af"}],"_type":"block","_key":"936bd87e6121"},{"language":"typescript","code":"import Model, { attr } from '@ember-data/model';\nimport { number, string } from 'yup';\nimport Validator from 'app/utils/validations';\n\ndeclare module 'ember-data/types/registries/model' {\n export default interface ModelRegistry {\n 'my-model': MyModel;\n }\n}\n\nconst validations = {\n someString: string()\n .min(12, 'Enter a valid string')\n .max(13, 'Enter a valid string')\n .required('Enter a string'),\n someNumber: number().required('Enter a number')\n};\n\nexport default class MyModel extends Model {\n validator = new Validator(this, validations);\n\n @attr('string') someString!: string;\n @attr('number') someNumber!: number;\n}\n","_type":"code","_key":"181b1544d280"},{"style":"normal","markDefs":[],"children":[{"text":"Now, let's call ","marks":[],"_type":"span","_key":"f942325ed3a1"},{"text":"validate()","marks":["code"],"_type":"span","_key":"8916e52adc27"},{"text":" on its Validator instance:","marks":[],"_type":"span","_key":"8c00fd9a0321"}],"_type":"block","_key":"c7fd5218ae09"},{"language":"typescript","code":"import Route from '@ember/routing/route';\nimport { action } from '@ember/object';\nimport { service } from '@ember/service';\n\nimport type { StoreService } from '@ember-data/store';\n\nexport default class MyRoute extends Route {\n @service declare store: StoreService;\n\n model(params) {\n return {\n someRecord: this.store.findRecord('my-model', { id: params.id })\n };\n }\n\n @action\n async save() {\n const { isValid, attrs } = await this.model.someRecord.validator.validate();\n\n if (isValid) {\n return this.model.someRecord.save();\n } else {\n // All Validated attributes are present on `attrs`\n attrs.someString // => { messages: string[]; isValid: boolean; value?: string; previousValue?: string }\n\n return false;\n }\n }\n}\n","_type":"code","_key":"e4e7b0f35b63"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"631b1f30fdf4"}],"_type":"block","_key":"ff3b233cd072"},{"style":"h1","markDefs":[],"children":[{"text":"Wrapping Up","marks":[],"_type":"span","_key":"a8811849aec60"}],"_type":"block","_key":"13712c68781f"},{"style":"normal","markDefs":[],"children":[{"text":"Building this out, I had a chance to dive much deeper into TypeScript utility types and generics than previously. I'm quite happy with the end result; a type-safe validation utility which can be used across our Ember application with confidence. Swapping out Computed Properties for Tracked properties isn't just a box-ticking exercise; it's a necessary step towards making the codebase more maintainable and future-proof.","marks":[],"_type":"span","_key":"7f0fab403c9e"}],"_type":"block","_key":"66ac6a97073d"},{"style":"normal","markDefs":[],"children":[{"text":"My choice to use ","marks":[],"_type":"span","_key":"b9f768cbd8ac0"},{"text":"yup","marks":["code"],"_type":"span","_key":"9504ae4703a6"},{"text":" over other validation libraries came after weighing the trade-offs for this specific use-case. Ultimately, I think any of the mentioned libraries would be great fits, it just came down to my preference for ","marks":[],"_type":"span","_key":"6d00986b1360"},{"text":"yup","marks":["code"],"_type":"span","_key":"42c7295b451b"},{"text":"'s syntax.","marks":[],"_type":"span","_key":"76e204f432cb"}],"_type":"block","_key":"78e893056552"},{"style":"normal","markDefs":[{"newtab":false,"href":"/etc","external":false,"_type":"link","_key":"4753c30a0391"}],"children":[{"text":"I hope sharing this experience offers some valuable insights or ideas for your own projects, whether you're working with Ember or any other framework. If you have questions or want to discuss any part of this in more detail (","marks":[],"_type":"span","_key":"945c9c0e75780"},{"text":"cough cough","marks":["em"],"_type":"span","_key":"2502f11aa13a"},{"text":", or if I made any mistakes), ","marks":[],"_type":"span","_key":"55b56b565eef"},{"text":"feel free to reach out","marks":["4753c30a0391"],"_type":"span","_key":"52d1cb8326b5"},{"text":"!","marks":[],"_type":"span","_key":"b025cc46a3ac"}],"_type":"block","_key":"fbc88377099c"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"376f9d1d05890"}],"_type":"block","_key":"d86f0c0b5f1a"}],"_type":"post","_rev":"BRxxHYbvnOye3Rn7rJiYD5","_id":"fa9d347d-7433-422c-93cc-2ebd9f507563"},{"views":4481,"title":"Mixing WebSockets & HTTP endpoints in Elixir with Cowboy + Plug","tags":[{"title":"Elixir","slug":{"current":"elixir","_type":"slug"},"_id":"04ba8a72-67bd-4767-84b0-750f96f77bb6"},{"title":"Networking","slug":{"current":"networking","_type":"slug"},"_id":"963e8717-7b88-4581-91ec-cdf872b8f463"},{"title":"Web Development","slug":{"current":"web-development","_type":"slug"},"_id":"3078b0c1-7c5e-4759-8bb3-5937fd09208b"}],"slug":{"current":"mixing-websockets-and-http-endpoints-in-elixir-with-cowboy-plug","_type":"slug"},"numberOfCharacters":2851,"headings":[{"typeLevel":2,"children":[],"key":"b294058b8e4b","text":"Creating a Custom Dispatcher Structure","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"722795c3f305","text":"Stub HTTP Router","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"2a104ab2dc7f","text":"WebSocket Handler","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"7770f3363ab7","text":"Profit (?)","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"a3a59329ca8d","text":"More resources","type":"h2","parent":null}],"estimatedWordCount":570,"estimatedReadingTime":5,"desc":"Using a custom dispatcher structure for mixing HTTP and WebSocket endpoints in a simple Plug-based Elixir API","date":"2023-07-20","body":[{"style":"normal","markDefs":[],"children":[{"text":"Howdy! 🤠","marks":[],"_type":"span","_key":"7aab34d647ce"}],"_type":"block","_key":"17b0ffc93d71"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"c1d4cb6f4340"}],"_type":"block","_key":"a61f946aaebd"},{"style":"normal","markDefs":[],"children":[{"text":"I recently found myself wanting to add a WebSocket endpoint to an existing Plug-based Elixir API I'd built with ","marks":[],"_type":"span","_key":"f8def3dad07c"},{"text":"Cowboy","marks":["notranslate"],"_type":"span","_key":"06bc60703987"},{"text":". It seemed like a straightforward task, but I found pretty sparse information online about it. After a weekend spent looking through ","marks":[],"_type":"span","_key":"a326674156bd"},{"text":"Hexdocs","marks":["notranslate"],"_type":"span","_key":"edcf40edf240"},{"text":" & ","marks":[],"_type":"span","_key":"968c43e85ab7"},{"text":"Cowboy","marks":["notranslate"],"_type":"span","_key":"c7b11628c3af"},{"text":"'s documentation, I figured I'd write a short post about my solution. ","marks":[],"_type":"span","_key":"3ad02a8bf008"}],"_type":"block","_key":"cada2e068a1d"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"5857602c5910"}],"_type":"block","_key":"8f1551581250"},{"style":"normal","markDefs":[],"children":[{"text":"My reason for using ","marks":[],"_type":"span","_key":"45d726074ac6"},{"text":"Cowboy","marks":["notranslate"],"_type":"span","_key":"958d4c197973"},{"text":" in the first place comes partly from stubbornness. Frameworks like Phoenix offer useful abstractions and utilities, but I prefer the lightweight & more minimalist approach provided by libraries like Cowboy. I find it gives more granular control over request handling, and is nicer to work with for smaller-scale applications.","marks":[],"_type":"span","_key":"50a2f071ff31"}],"_type":"block","_key":"a94d7fa49133"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"d04d5bfa5708"}],"_type":"block","_key":"394c77afc474"},{"style":"h2","markDefs":[],"children":[{"text":"Creating a Custom Dispatcher Structure","marks":[],"_type":"span","_key":"945df603912d"}],"_type":"block","_key":"b294058b8e4b"},{"style":"normal","markDefs":[],"children":[{"text":"Assuming your application follows the typical Elixir structure, we need to define a custom dispatcher structure for the ","marks":[],"_type":"span","_key":"ceb5ee6579aa"},{"text":"Cowboy","marks":["notranslate"],"_type":"span","_key":"6e280cc1c610"},{"text":" child spec in your supervision tree. This dispatcher structure is used for designating a separate module for handling any WebSocket requests we get, keeping that handling separate from any HTTP routes. ","marks":[],"_type":"span","_key":"340678110a8c"}],"_type":"block","_key":"a0697c23acf3"},{"language":"elixir","filename":"application.ex","code":"defmodule MyApplication do\n use Application\n\n defp dispatcher do\n [\n {:_, [\n {\"/websocket\", MyApplication.SocketRouter, []},\n {:_, Plug.Cowboy.Handler, {MyApplication.Router, []}},\n ]}\n ]\n end\n\n @impl true\n def start _type, _args do\n children = [\n {\n Plug.Cowboy,\n scheme: :http,\n plug: MyApplication.Router,\n options: [\n port: 3000,\n dispatch: dispatcher,\n ],\n }\n ]\n\n opts = [strategy: :one_for_one, name: __MODULE__]\n\n Supervisor.start_link children, opts\n end\nend","_type":"code","_key":"5349fb65ec32"},{"style":"normal","markDefs":[],"children":[{"text":"In this minimal example, we define a dispatcher structure that routes requests starting with \"/websocket\" to the ","marks":[],"_type":"span","_key":"862004368a54"},{"text":"SocketRouter","marks":["code"],"_type":"span","_key":"2a34536a9948"},{"text":" module, while ","marks":[],"_type":"span","_key":"48d32934bef9"},{"text":"Router","marks":["code"],"_type":"span","_key":"a73188ef5d44"},{"text":" handles all other paths. Since the order is hierarchical, the WebSocket route comes first, followed by the ","marks":[],"_type":"span","_key":"4f20da1b51ab"},{"text":":_","marks":["code"],"_type":"span","_key":"a6d29e1b03a0"},{"text":" catch-all atom for any others.","marks":[],"_type":"span","_key":"2f21d86b79d9"}],"_type":"block","_key":"ab9cf4d054cd"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"6578f67f4e48"}],"_type":"block","_key":"6bae815bc6c7"},{"style":"h2","markDefs":[],"children":[{"text":"Stub HTTP Router","marks":[],"_type":"span","_key":"0be5383cc4ca"}],"_type":"block","_key":"722795c3f305"},{"style":"normal","markDefs":[],"children":[{"text":"For the purpose of this writeup, we'll use a super minimal HTTP router module that simply responds with \"Hello, world\" to any request:","marks":[],"_type":"span","_key":"e61c47a0bd75"}],"_type":"block","_key":"36aabd7f8b2b"},{"language":"elixir","filename":"router.ex","code":"defmodule MyApplication.Router do\n use Plug.Router\n\n plug :match\n plug :dispatch\n\n match _ do\n send_resp conn, 200, \"Hello, world!\"\n end\nend","_type":"code","_key":"fc514d940d39"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"3af628f4d4ce"}],"_type":"block","_key":"0bbd33ab4831"},{"style":"h2","markDefs":[],"children":[{"text":"WebSocket Handler","marks":[],"_type":"span","_key":"cd2ff2a25840"}],"_type":"block","_key":"2a104ab2dc7f"},{"language":"elixir","filename":"ws_router.ex","code":"defmodule MyApplication.SocketRouter do\n @behaviour :cowboy_websocket_handler\n\n def init req, _opts do\n {\n :cowboy_websocket,\n req,\n %{},\n %{\n # 1 min w/o a ping from the client and the connection is closed\n idle_timeout: 60_000,\n # Max incoming frame size of 1 MB\n max_frame_size: 1_000_000,\n }\n }\n end\n\n def websocket_init state \\\\ %{} do\n {:ok, state}\n end\n\n # Handle 'ping' frames\n def websocket_handle {:text, \"ping\"}, req, state do\n {:reply, {:text, \"pong\"}, req, state}\n end\n\n # Ignore all other text frames\n def websocket_handle {:text, _msg}, req, state do\n {:ok, req, state}\n end\n\n def websocket_info msg, req, state do\n {:reply, {:text, msg}, req, state}\n end\n\n def terminate _reason, _req, _state do\n :ok\n end\nend","_type":"code","_key":"dc27d351d050"},{"style":"normal","markDefs":[],"children":[{"text":"Here, we specify that the module conforms to the ","marks":[],"_type":"span","_key":"e38649568a69"},{"text":":cowboy_websocket_handler","marks":["code"],"_type":"span","_key":"87ffd757c45c"},{"text":" behaviour using ","marks":[],"_type":"span","_key":"5b729fa9b2db"},{"text":"@behaviour","marks":["code"],"_type":"span","_key":"14d97d8c41dc"},{"text":". This consists of a few callbacks:","marks":[],"_type":"span","_key":"4ae5c2d7d991"}],"_type":"block","_key":"fa8313240db7"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"init/2","marks":["code"],"_type":"span","_key":"c43ca4117286"},{"text":" initializes the WebSocket handler and specifies any options (in this case, just overriding the default ","marks":[],"_type":"span","_key":"d179a1309c40"},{"text":"idle_timeout","marks":["code"],"_type":"span","_key":"e65f7a7858e3"},{"text":" and ","marks":[],"_type":"span","_key":"c8a17836f986"},{"text":"max_frame_size","marks":["code"],"_type":"span","_key":"4129df3202fe"},{"text":").","marks":[],"_type":"span","_key":"93dd4b86aa0e"}],"_type":"block","_key":"88bb87526f26"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"websocket_init/1","marks":["code"],"_type":"span","_key":"b29a16e69c0f"},{"text":" initializes the specific WebSocket connection and sets up the initial state.","marks":[],"_type":"span","_key":"54d0d666983f"}],"_type":"block","_key":"418d6bb190c0"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"websocket_handle/3","marks":["code"],"_type":"span","_key":"b180a68daaac"},{"text":" handles specific WebSocket frames, such as responding to ","marks":[],"_type":"span","_key":"8c92bcb7bc2a"},{"text":":ping","marks":["code"],"_type":"span","_key":"e602ae3f94a2"},{"text":" frames with a ","marks":[],"_type":"span","_key":"7d6a1bed0322"},{"text":":text","marks":["code"],"_type":"span","_key":"1413ab758fc9"},{"text":" response of \"pong\".","marks":[],"_type":"span","_key":"dba48b69e12f"}],"_type":"block","_key":"d0c30b1108d9"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"websocket_info/3","marks":["code"],"_type":"span","_key":"4dd463138d1c"},{"text":" handles any Elixir messages recieved from other parts of the application, and forwards them to the WebSocket client.","marks":[],"_type":"span","_key":"903bfc438f6e"}],"_type":"block","_key":"d06b123594c8"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"terminate/3","marks":["code"],"_type":"span","_key":"c7fd6b388cd2"},{"text":" is called upon termination and allows performing cleanup tasks such as terminating other processes.","marks":[],"_type":"span","_key":"cfb51f00dc02"}],"_type":"block","_key":"0b33faea233d"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"03105a417f76"}],"_type":"block","_key":"2b35498cf6ea"},{"style":"h2","markDefs":[],"children":[{"text":"Profit (?)","marks":[],"_type":"span","_key":"1417e782c55a"}],"_type":"block","_key":"7770f3363ab7"},{"style":"normal","markDefs":[],"children":[{"text":"With the demo app running locally, we can see these endpoints in action! First up, the HTTP router:","marks":[],"_type":"span","_key":"c4ec4e1ff09a"}],"_type":"block","_key":"a04cc673b243"},{"language":"shell","code":"$ curl -i http://localhost:3000\nHTTP/1.1 200 OK\nContent-Type: text/plain; charset=utf-8\nContent-Length: 13\n\nHello, world!","_type":"code","_key":"4aeee8e65364"},{"style":"normal","markDefs":[],"children":[{"text":"And next, the WebSocket router:","marks":[],"_type":"span","_key":"346944812a71"}],"_type":"block","_key":"a64932a03bee"},{"language":"shell","code":"$ wscat -c ws://localhost:3000/websocket\nConnected (press CTRL+C to quit)","_type":"code","_key":"8c181fb605e9"},{"style":"normal","markDefs":[],"children":[{"text":"Once connected, sending a text frame of \"ping\" yields a response of \"pong\", as expected:","marks":[],"_type":"span","_key":"b3b2417ca56d"}],"_type":"block","_key":"564898f8e2a8"},{"language":"shell","code":"> ping\n< pong","_type":"code","_key":"6230c96cdf21"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"6d448937732a"}],"_type":"block","_key":"3d0bbe30e829"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"b71ee4ee7a98"}],"_type":"block","_key":"a0cf5c7042f1"},{"style":"normal","markDefs":[],"children":[{"text":"So there you have it! I hope this quick overview is useful; I've personally loved working with Cowboy so far and am glad I was able to make it work for this use-case of mine 😁","marks":[],"_type":"span","_key":"f9593d88fde80"}],"_type":"block","_key":"220629c755c1"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"e50d6641c857"}],"_type":"block","_key":"e26d599e624a"},{"style":"h2","markDefs":[],"children":[{"text":"More resources","marks":[],"_type":"span","_key":"f52577763d90"}],"_type":"block","_key":"a3a59329ca8d"},{"style":"normal","markDefs":[],"children":[{"text":"The full docs for ","marks":[],"_type":"span","_key":"05e3c27853a4"},{"text":"cowboy_websocket","marks":["code"],"_type":"span","_key":"c0cc3431cbf3"},{"text":" are worth a read:","marks":[],"_type":"span","_key":"69233e9830c4"}],"_type":"block","_key":"2ad5292b112e"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://ninenines.eu/docs/en/cowboy/2.7/manual/cowboy_websocket/","external":true,"_type":"link","_key":"4ae4a90274f4"}],"listItem":"bullet","level":1,"children":[{"text":"https://ninenines.eu/docs/en/cowboy/2.7/manual/cowboy_websocket/","marks":["4ae4a90274f4"],"_type":"span","_key":"2cfbf09fa4980"}],"_type":"block","_key":"db56e5cdbfe5"}],"_type":"post","_rev":"BRxxHYbvnOye3Rn7rK2rIZ","_id":"0e4cac08-a76c-4235-9a94-0f86be6a682f"},{"views":611,"title":"Chaining Javascript Style Calls with Proxies","tags":[{"title":"Javascript","slug":{"current":"javascript","_type":"slug"},"_id":"800d2af5-28a2-43a5-acf8-f2dbca2a7c11"},{"title":"Typescript","slug":{"current":"typescript","_type":"slug"},"_id":"f12e4792-7b17-4130-8eb5-dd09d2477241"}],"slug":{"current":"chaining-javascript-style-calls-with-proxies","_type":"slug"},"numberOfCharacters":4083,"headings":[{"typeLevel":2,"children":[],"key":"756c6afb3b93","text":"What are Proxies?","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"834d814477c9","text":"Method","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"7aabb1cf4518","text":"More Use-cases","type":"h2","parent":null},{"typeLevel":2,"children":[{"typeLevel":3,"children":[],"key":"3c27784e983d","text":"More resources","type":"h3","parent":"be10263f4294"}],"key":"be10263f4294","text":"Potential Issues","type":"h2","parent":null}],"estimatedWordCount":817,"estimatedReadingTime":7,"desc":"A quick demonstration on how Proxies function in JavaScript","date":"2022-08-27","body":[{"style":"normal","markDefs":[],"children":[{"text":"Mixed feelings about jQuery aside, it's hard to argue against the ease it brings to some tasks compared with vanilla JavaScript. One such feature is its ability to chain method calls, meaning instead of referencing a DOM element repeatedly, you can keep chaining instructions without interruption.","marks":[],"_type":"span","_key":"16c29b0649fb0"}],"_type":"block","_key":"2fdb864e904d"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"0c8e4cbf72d5"}],"_type":"block","_key":"36168ed4e54a"},{"style":"normal","markDefs":[],"children":[{"text":"Here's a concrete example: if you're looking to adjust the color and width of ","marks":[],"_type":"span","_key":"acec262dae470"},{"text":".someClass","marks":["code"],"_type":"span","_key":"acec262dae471"},{"text":" and want a fade effect:","marks":[],"_type":"span","_key":"acec262dae472"}],"_type":"block","_key":"1c3f478fa581"},{"language":"javascript","code":"$('.someClass')\n .css('color', '#fafafa')\n .css('width', '100%')\n .fadeIn();","_type":"code","_key":"19dae2d94be2"},{"style":"normal","markDefs":[],"children":[{"text":"Doing this in plain JavaScript would require a bit more code and doesn't feel quite as smooth:","marks":[],"_type":"span","_key":"172b890997ba0"}],"_type":"block","_key":"73da5318e81e"},{"language":"javascript","code":"const someObject = document.querySelector('.someClass');\n\nsomeObject.style.color = '#fafafa';\nsomeObject.style.width = '100%';\nsomeObject.style.transition = 'opacity 250ms ease';\nsomeObject.style.opacity = '1.0';","_type":"code","_key":"5e22e70a37dd"},{"style":"normal","markDefs":[],"children":[{"text":"But, as an example in using JavaScript Proxies, we can make the process cleaner and allow chained calls to ","marks":[],"_type":"span","_key":"5552321f1276"},{"text":"element.style","marks":["code"],"_type":"span","_key":"b6040a257d79"},{"text":":","marks":[],"_type":"span","_key":"9dc0f435fc53"}],"_type":"block","_key":"dd5f0613774c"},{"language":"javascript","code":"style('.someObject')\n .color('#fafafa')\n .width('100%')\n .transition('opacity 250ms ease')\n .opacity('1.0');","_type":"code","_key":"4c6fcc55f987"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"09805cfa7046"}],"_type":"block","_key":"33921e80c438"},{"style":"h2","markDefs":[],"children":[{"text":"What are Proxies?","marks":[],"_type":"span","_key":"3f834ea7f348"}],"_type":"block","_key":"756c6afb3b93"},{"style":"normal","markDefs":[],"children":[{"text":"In JavaScript, a Proxy is an object that sits between a target object and the external code trying to interact with it. When you create a Proxy, you specify what operations (like ","marks":[],"_type":"span","_key":"1dbc4f0582340"},{"text":"gets","marks":["code"],"_type":"span","_key":"815bcd929de0"},{"text":" or ","marks":[],"_type":"span","_key":"db4d28de39e4"},{"text":"sets","marks":["code"],"_type":"span","_key":"9396901dc9de"},{"text":") it should intercept. The Proxy then intercepts any of those operations made to the target object.","marks":[],"_type":"span","_key":"97136e1827f1"}],"_type":"block","_key":"81bc29371b27"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"9f040a5859ea"}],"_type":"block","_key":"21a94db1d923"},{"style":"normal","markDefs":[],"children":[{"text":"Here's a very simple example which intercepts all ","marks":[],"_type":"span","_key":"15db58c36383"},{"text":"gets","marks":["code"],"_type":"span","_key":"7941efb8d147"},{"text":":","marks":[],"_type":"span","_key":"217e8869d51d"}],"_type":"block","_key":"79c9d76c91e7"},{"language":"javascript","code":"const target = {};\nconst handler = {\n get: (target, name) {\n return `Hello, ${name}!`;\n }\n};\nconst proxy = new Proxy(target, handler);\n\nconsole.log(proxy.name); // => \"Hello, name!\"\nconsole.log(proxy.otherName); // => \"Hello, otherName!\"","_type":"code","_key":"1740d71ec5de"},{"style":"normal","markDefs":[],"children":[{"text":"The ","marks":[],"_type":"span","_key":"bcd22c95fe2a"},{"text":"proxy","marks":["code"],"_type":"span","_key":"ed2e797a53f4"},{"text":" is acting as an intermediary for the ","marks":[],"_type":"span","_key":"9846be371b2b"},{"text":"target","marks":["code"],"_type":"span","_key":"c078a6f2a8d0"},{"text":"; the ","marks":[],"_type":"span","_key":"07c849b07f28"},{"text":"handler","marks":["code"],"_type":"span","_key":"124a45e35d63"},{"text":" defining its behaviour, in this case, overriding the getter for any property and returning a string containing the property name.","marks":[],"_type":"span","_key":"f7343dca97a6"}],"_type":"block","_key":"64c379d071db"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"c67dac547553"}],"_type":"block","_key":"cdf8abf9a140"},{"style":"h2","markDefs":[],"children":[{"text":"Method","marks":[],"_type":"span","_key":"f096427ba638"}],"_type":"block","_key":"834d814477c9"},{"style":"normal","markDefs":[],"children":[{"text":"Given this foundation, we can set up a Proxy to allow chained style changes, much like what jQuery offers:","marks":[],"_type":"span","_key":"60d48d62e9760"}],"_type":"block","_key":"894c3f358993"},{"style":"normal","markDefs":[],"listItem":"number","level":1,"children":[{"text":"Get the element with a given selector.","marks":[],"_type":"span","_key":"47019cde66830"}],"_type":"block","_key":"c757728ef1ec"},{"style":"normal","markDefs":[],"listItem":"number","level":1,"children":[{"text":"Use a Proxy to watch all interactions.","marks":[],"_type":"span","_key":"c8669d78593e0"}],"_type":"block","_key":"6ad2c287d4bd"},{"style":"normal","markDefs":[],"listItem":"number","level":1,"children":[{"text":"Update the value of any accessed property.","marks":[],"_type":"span","_key":"6bb440f447e80"}],"_type":"block","_key":"04a4fdcd57fb"},{"style":"normal","markDefs":[],"listItem":"number","level":1,"children":[{"text":"Return the Proxy for further chaining.","marks":[],"_type":"span","_key":"99db5ad118900"}],"_type":"block","_key":"e60aa6a2b9d3"},{"style":"normal","markDefs":[],"children":[{"text":"By doing this, you can keep chaining methods without needing a temporary variable to hold the element. It remains in memory.","marks":[],"_type":"span","_key":"0553c10273d00"}],"_type":"block","_key":"11efbb7ad8cc"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"bb5bd7156c71"}],"_type":"block","_key":"cb89e2fe5a24"},{"style":"normal","markDefs":[],"children":[{"text":"Since this particular method involves repurposing the getter to act as a setter, we can keep its functionality by returning the value of a specified property if no additional arguments are passed (also similar to how jQuery functions). For example, you can check the value of ","marks":[],"_type":"span","_key":"7ea52f2ff8ca"},{"text":"backgroundColor","marks":["code"],"_type":"span","_key":"8ef786e221fa"},{"text":" with ","marks":[],"_type":"span","_key":"1e6b25331f3e"},{"text":"style('.someDomObject').backgroundColor()","marks":["code"],"_type":"span","_key":"27986297751c"},{"text":".","marks":[],"_type":"span","_key":"971db5d23688"}],"_type":"block","_key":"a067f06d8210"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"fb2bf1fa3d66"}],"_type":"block","_key":"2d25a5b2b147"},{"language":"javascript","code":"const proxy = {\n get: (obj, prop) => {\n return (value) => {\n if (value) {\n obj[prop] = value;\n return new Proxy(obj, proxy);\n }\n return obj[prop];\n }\n }\n};\n\nexport const style = (selector) => {\n const element = document.querySelector(selector);\n return element\n ? new Proxy(element.style, proxy)\n : undefined;\n};","_type":"code","_key":"29f3626ae529"},{"style":"normal","markDefs":[],"children":[{"text":"And that's it! We can now import this ","marks":[],"_type":"span","_key":"93abc60d16c2"},{"text":"style","marks":["code"],"_type":"span","_key":"5fcb35ea924c"},{"text":" function and chain it for changing DOM element styles.","marks":[],"_type":"span","_key":"1e16a9b009c3"}],"_type":"block","_key":"59092ba50660"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"b252c0316161"}],"_type":"block","_key":"e09c25c181f3"},{"style":"h2","markDefs":[],"children":[{"text":"More Use-cases","marks":[],"_type":"span","_key":"07df392a7b81"}],"_type":"block","_key":"7aabb1cf4518"},{"style":"normal","markDefs":[],"children":[{"text":"Proxies offer a lot more flexibility and functionality beyond just chaining style changes:","marks":[],"_type":"span","_key":"f5cb346034bb0"}],"_type":"block","_key":"8c48bcfdb7ec"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"Logging:","marks":["strong"],"_type":"span","_key":"cae4d28048a30"},{"text":" By monitoring method calls on objects, Proxies allow keeping closer track of details. This includes identifying which methods are being called, understanding the arguments being passed, and analyzing return values. This capability can be immensely powerful when debugging, as it gives a more transparent view of interactions.","marks":[],"_type":"span","_key":"cae4d28048a31"}],"_type":"block","_key":"9c70b125c4fb"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"Data Checks:","marks":["strong"],"_type":"span","_key":"40c70bef85550"},{"text":" Data integrity is crucial in many applications. With Proxies, you can set up barriers to validate data inputs, ensuring they meet criteria before being applied to the target.","marks":[],"_type":"span","_key":"40c70bef85551"}],"_type":"block","_key":"ecbfa20feb7f"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"Control and Storage:","marks":["strong"],"_type":"span","_key":"993c432c5d390"},{"text":" Proxies allow for a fine level of control over object interactions. By using tools like ","marks":[],"_type":"span","_key":"993c432c5d391"},{"text":"WeakMap","marks":["code"],"_type":"span","_key":"993c432c5d392"},{"text":" alongside Proxies, you can manage data changes in a more efficient manner - This could mean buffering changes and then applying them all at once, leading to performance benefits in specific scenarios, or allowing rollbacks of changes.","marks":[],"_type":"span","_key":"993c432c5d393"}],"_type":"block","_key":"5a1dad8d6dd9"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"95c00c10bafa"}],"_type":"block","_key":"367736b31be3"},{"style":"h2","markDefs":[],"children":[{"text":"Potential Issues","marks":[],"_type":"span","_key":"a8514e8ccf210"}],"_type":"block","_key":"be10263f4294"},{"style":"normal","markDefs":[],"children":[{"text":"While Proxies bring many advantages to the table, it's good to be aware of their limitations:","marks":[],"_type":"span","_key":"1547a60e853b0"}],"_type":"block","_key":"3949e81494a2"},{"style":"normal","markDefs":[],"listItem":"number","level":1,"children":[{"text":"Speed:","marks":["strong"],"_type":"span","_key":"48df2186e3990"},{"text":" Every layer of abstraction has a cost, and Proxies are no exception. Intensive use of Proxies, especially in performance-critical scenarios, can introduce noticeable overhead.","marks":[],"_type":"span","_key":"48df2186e3991"}],"_type":"block","_key":"784af341ac34"},{"style":"normal","markDefs":[],"listItem":"number","level":1,"children":[{"text":"Learning Curve:","marks":["strong"],"_type":"span","_key":"0b1fd139d0e10"},{"text":" For those unfamiliar with the concept, understanding and working with Proxies can present a challenge. They introduce a level of indirection that isn't intuitive.","marks":[],"_type":"span","_key":"0b1fd139d0e11"}],"_type":"block","_key":"46924e27c8cf"},{"style":"normal","markDefs":[],"listItem":"number","level":1,"children":[{"text":"Type Issues:","marks":["strong"],"_type":"span","_key":"0f1f24fb4e120"},{"text":" When working with TypeScript, altering the behaviour of the underlying object with Proxies can lead to type inconsistencies. TypeScript relies on static types, and if a Proxy modifies an object's behaviour in a way that isn't reflected in its type definitions, it can be a pain to deal with.","marks":[],"_type":"span","_key":"0f1f24fb4e121"}],"_type":"block","_key":"1f7f15bbc598"},{"style":"normal","markDefs":[],"listItem":"number","level":1,"children":[{"text":"Issues with Inheritance:","marks":["strong"],"_type":"span","_key":"2081ca2f4e9d0"},{"text":" Proxies can be tricky when dealing with inherited properties. They may not always behave as expected, especially if the properties are deep within the prototype chain.","marks":[],"_type":"span","_key":"2081ca2f4e9d1"}],"_type":"block","_key":"46b367d503d7"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"a42101f9ed8d"}],"_type":"block","_key":"dc1a9d28d77e"},{"style":"h3","markDefs":[],"children":[{"text":"More resources","marks":[],"_type":"span","_key":"98caea73e307"}],"_type":"block","_key":"3c27784e983d"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy","external":true,"_type":"link","_key":"39ec63a38d2d"}],"listItem":"bullet","level":1,"children":[{"text":"MDN","marks":["39ec63a38d2d"],"_type":"span","_key":"f4071879975d"}],"_type":"block","_key":"a5bc67a78b1d"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://medium.com/swlh/javascript-proxies-reshaping-data-ca151d4d24a0","external":true,"_type":"link","_key":"c408e9e525f0"}],"listItem":"bullet","level":1,"children":[{"text":"JavaScript Proxies: Reshaping Data","marks":["c408e9e525f0"],"_type":"span","_key":"91449c0a7aaa"}],"_type":"block","_key":"66266113630c"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"d0f684a80073"}],"_type":"block","_key":"4894a3cb7cd3"}],"_type":"post","_rev":"3GUDmcZdXMS7XYzeGej5Q5","_id":"3cbdb119-99ee-4493-a9f3-9f2a4b4ba64c"},{"views":1422,"title":"Custom Notifications with 'gdbus call' + 'wired-notify'","tags":[{"title":"Linux","slug":{"current":"linux","_type":"slug"},"_id":"f5ced506-6b69-4557-b4e8-819845089b42"},{"title":"Guides","slug":{"current":"guides","_type":"slug"},"_id":"4501a332-2a0c-4baf-8281-bf59862a250d"}],"slug":{"current":"custom-notifications-with-gdbus-call-wired-notify","_type":"slug"},"numberOfCharacters":2865,"headings":[{"typeLevel":2,"children":[],"key":"3e011a1fa8af","text":"Syntax","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"7396c3660541","text":"Body text","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"81c8c5b46635","text":"Providing hints","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"acdb8aa95389","text":"More configs","type":"h2","parent":null}],"estimatedWordCount":573,"estimatedReadingTime":5,"desc":null,"date":"2022-06-09","body":[{"style":"normal","markDefs":[],"children":[{"text":"I wanted to write this short guide on the functionality of ","marks":[],"_type":"span","_key":"5d69664a0f6a0"},{"text":"gdbus call","marks":["code"],"_type":"span","_key":"5d69664a0f6a1"},{"text":" as I couldn't find any resources online regarding it besides its own documentation. I'll also quickly cover my ","marks":[],"_type":"span","_key":"5d69664a0f6a2"},{"text":"wired-notify","marks":["code"],"_type":"span","_key":"a922c3eb0c1b"},{"text":" config, since it's a really neat notification daemon that I don't think is nearly popular enough :)","marks":[],"_type":"span","_key":"621ebdefdc63"}],"_type":"block","_key":"7d548f46991d"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"8045d14eb3c3"}],"_type":"block","_key":"d04968177e01"},{"style":"normal","markDefs":[],"children":[{"text":"Here's the reason I went through this trouble, first off - a tiny configurable volume HUD that live-updates in place as you change the device volume!","marks":[],"_type":"span","_key":"fe3bbefbea95"}],"_type":"block","_key":"a87287ad421c"},{"asset":{"_type":"reference","_ref":"image-86c5e280ca452fe59cc97707e3f2464a5bc37154-830x594-png"},"_type":"image","_key":"c36338ff1ef3"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"ab3a22008713"}],"_type":"block","_key":"ee3e6c7a7785"},{"style":"normal","markDefs":[],"children":[{"text":"Although ","marks":[],"_type":"span","_key":"14ef1cfbb4e9"},{"text":"gdbus call","marks":["code"],"_type":"span","_key":"fc8371575699"},{"text":" has ","marks":[],"_type":"span","_key":"188535e54937"},{"text":"many","marks":["em"],"_type":"span","_key":"3715de369504"},{"text":" use-cases, the one I'll focus on here is sending custom notifications, as notify-send doesn't expose many of the properties I needed to set. ","marks":[],"_type":"span","_key":"87d58ddb6cf7"},{"text":"notify-send","marks":["code"],"_type":"span","_key":"0b33fe4e9ca7"},{"text":", along with other notification frameworks I looked at, didn't support updating existing notifications using identifiers. ","marks":[],"_type":"span","_key":"db8705dba634"},{"text":"gdbus call","marks":["code"],"_type":"span","_key":"86834cc5a650"},{"text":" does allow this granular control, along with exposing some other cool properties.","marks":[],"_type":"span","_key":"90fb38bd6d05"}],"_type":"block","_key":"1c9c20a48c7c"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"9f02ca017492"}],"_type":"block","_key":"2932db0408ed"},{"style":"h2","markDefs":[],"children":[{"text":"Syntax","marks":[],"_type":"span","_key":"cc6ddd8a9ffc"}],"_type":"block","_key":"3e011a1fa8af"},{"language":"shell","code":"gdbus call \\\n --session \\\n --dest org.freedesktop.Notifications \\\n --object-path /org/freedesktop/Notifications \\\n --method org.freedesktop.Notifications.Notify \\\n -- \\\n \"identifier\" \\\n \"1\" \\\n \"\" \\\n \"Notification title\" \\\n \"Notification description\" \\\n \"[]\" \\\n \"{}\" \\\n \"4000\"","_type":"code","_key":"b2f120c2d04f"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"f2f883ee70940"}],"_type":"block","_key":"c7ecedbe1da3"},{"style":"normal","markDefs":[],"children":[{"text":"Running this will return ","marks":[],"_type":"span","_key":"1fd3b4b4f9610"},{"text":"(uint32 1,)","marks":["code"],"_type":"span","_key":"1fd3b4b4f9611"},{"text":", the '1' representing the notification's unique identifier. This is useful if you want to parse that identifier and re-use it later; one way to do so would be using sed (e.g., ","marks":[],"_type":"span","_key":"1fd3b4b4f9612"},{"text":"sed 's/[^ ]* //; s/,.//'","marks":["code"],"_type":"span","_key":"1fd3b4b4f9613"},{"text":" would strip everything but the identifier).","marks":[],"_type":"span","_key":"271cbde77471"}],"_type":"block","_key":"f4ead6505354"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"700c4fb32fdd"}],"_type":"block","_key":"78c64d22cd3e"},{"style":"normal","markDefs":[],"children":[{"text":"A few other tips:","marks":[],"_type":"span","_key":"ae11ff7c1f2d0"}],"_type":"block","_key":"febff50cd2fa"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"--session","marks":["code"],"_type":"span","_key":"f8dff7588a200"},{"text":" represents the user's ","marks":[],"_type":"span","_key":"1c0cab7c53fc"},{"text":"systemd --user","marks":["code"],"_type":"span","_key":"8258a7d64e95"},{"text":" instance","marks":[],"_type":"span","_key":"16e226a2b53b"}],"_type":"block","_key":"02968c46e729"},{"style":"normal","markDefs":[{"href":"https://specifications.freedesktop.org/notification-spec/notification-spec-latest.html","_type":"link","_key":"b33c85a9735a"}],"listItem":"bullet","level":1,"children":[{"text":"--dest","marks":["code"],"_type":"span","_key":"ed56127f56630"},{"text":", ","marks":[],"_type":"span","_key":"f7a8529dd201"},{"text":"--object-path","marks":["code"],"_type":"span","_key":"db3e7559ea21"},{"text":", and ","marks":[],"_type":"span","_key":"5776a4eb1679"},{"text":"--method","marks":["code"],"_type":"span","_key":"7449784af3e3"},{"text":" in this case are all used to point to freedesktop.notifications.notify, and the following parameters are specified in ","marks":[],"_type":"span","_key":"c154a92082a3"},{"text":"freedesktop's documentation","marks":["b33c85a9735a"],"_type":"span","_key":"ed56127f56631"}],"_type":"block","_key":"c19e8cdb9669"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"The '1' represents the identifier, and the replaces ID","marks":[],"_type":"span","_key":"cd6c4f0abc870"}],"_type":"block","_key":"78704799a937"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"The following blank string is the notification icon","marks":[],"_type":"span","_key":"2849f9a6fefb0"}],"_type":"block","_key":"a6171c1ccd91"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"The following two strings are for the Summary (notification title) and Body (multi-line description)","marks":[],"_type":"span","_key":"2fd74eb4a9dd0"}],"_type":"block","_key":"bfe27e7d5dec"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"The empty array is for actions, for ex, sending a callback to the application when clicked","marks":[],"_type":"span","_key":"1d8c7d210c4e0"}],"_type":"block","_key":"f896b7db56c7"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"The empty dictionary is for hints; these are used to send extra data such as (in my use case) the current volume level, an image, extra text, etc","marks":[],"_type":"span","_key":"3c100d383c5b0"}],"_type":"block","_key":"08d8568b7e29"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"The '4000' represents the expiration timeout in ms. If set to -1, it falls back to the notification server's default","marks":[],"_type":"span","_key":"a04e1b0c79a30"}],"_type":"block","_key":"88da341f31fb"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"d4dabec9a010"}],"_type":"block","_key":"cc2a6cc188c4"},{"style":"h2","markDefs":[],"children":[{"text":"Body text","marks":[],"_type":"span","_key":"404603f5e5020"}],"_type":"block","_key":"7396c3660541"},{"style":"normal","markDefs":[],"children":[{"text":"The body text can, in most cases, contain limited markup:","marks":[],"_type":"span","_key":"54f4a9b83c3e0"}],"_type":"block","_key":"c9d731fc33eb"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"... for bold,","marks":[],"_type":"span","_key":"1e4e5d068e0a0"}],"_type":"block","_key":"be7218b95975"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"... for italics,","marks":[],"_type":"span","_key":"f2980efe656b0"}],"_type":"block","_key":"955c9d1f4981"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"... for underlines,","marks":[],"_type":"span","_key":"869d2c4b6eab0"}],"_type":"block","_key":"1aa90bb80424"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"... for links, and","marks":[],"_type":"span","_key":"b5fc6d8517390"}],"_type":"block","_key":"de73ff4df03e"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":" $\"...\"$ ... for images","marks":[],"_type":"span","_key":"59c6225d3c200"}],"_type":"block","_key":"f450d3ffe639"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"21f7e29e83b7"}],"_type":"block","_key":"eb0e07998eb0"},{"style":"h2","markDefs":[],"children":[{"text":"Providing hints","marks":[],"_type":"span","_key":"5026fa3895fe0"}],"_type":"block","_key":"81c8c5b46635"},{"style":"normal","markDefs":[],"children":[{"text":"Hints are provided as a dictionary, using the following format:","marks":[],"_type":"span","_key":"829b1e8697720"}],"_type":"block","_key":"da6c2b0a35e9"},{"style":"normal","markDefs":[],"children":[{"text":"{'Name': <'type':'value'>}","marks":["code"],"_type":"span","_key":"792efafb8f3a0"}],"_type":"block","_key":"5b863fa857d6"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"1304c618fec5"}],"_type":"block","_key":"62b13c16acf1"},{"style":"normal","markDefs":[],"children":[{"text":"So, for example, sending a hint for the integer value of my volume notification looks like:","marks":[],"_type":"span","_key":"403c76714b320"}],"_type":"block","_key":"86d431d4cc90"},{"style":"normal","markDefs":[],"children":[{"text":"{'value': <58>}","marks":["code"],"_type":"span","_key":"70cd325c5fb20"}],"_type":"block","_key":"0777d9b0399a"},{"style":"normal","markDefs":[],"children":[{"text":"And for providing a file path for an image preview:","marks":[],"_type":"span","_key":"1457c9d027f20"}],"_type":"block","_key":"0ef4cd281c36"},{"style":"normal","markDefs":[],"children":[{"text":"{'image-path': <'file:///dir/image.jpg'}","marks":["code"],"_type":"span","_key":"e278ccfa31100"}],"_type":"block","_key":"27f10f1b8912"},{"style":"normal","markDefs":[],"children":[{"text":"Note that when providing the dictionary in the command, it should be encased by double-quotes.","marks":[],"_type":"span","_key":"6222f16e11910"}],"_type":"block","_key":"0d3617e81559"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"85af435ff7cd"}],"_type":"block","_key":"d114a9d9c9ed"},{"style":"normal","markDefs":[],"children":[{"text":"That's all there is to it! I hope this comes in handy for someone at some point :)","marks":[],"_type":"span","_key":"1bc5200606d1"}],"_type":"block","_key":"2f80f569c0b6"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"3afb23823be6"}],"_type":"block","_key":"d3371a3ef73d"},{"style":"h2","markDefs":[],"children":[{"text":"More configs","marks":[],"_type":"span","_key":"5276f3a8c20a"}],"_type":"block","_key":"acdb8aa95389"},{"style":"normal","markDefs":[],"children":[{"text":"Finally, if you're curious, here's my wired-notify config, as well as the simple script I call on volume update to send a notification to it:","marks":[],"_type":"span","_key":"c0165360102c0"}],"_type":"block","_key":"3e70290cce74"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"8960ae6966f7"}],"_type":"block","_key":"ccb945038878"},{"language":"shell","filename":"wired.ron","code":"(\n max_notifications: 4,\n timeout: 10000,\n poll_interval: 16,\n history_length: 20,\n replacing_enabled: true,\n replacing_resets_timeout: true,\n min_window_width: 300,\n\n debug: false,\n debug_color: Color(r: 0.0, g: 1.0, b: 0.0, a: 1.0),\n debug_color_alt: Color(r: 1.0, g: 0.0, b: 0.0, a: 1.0),\n\n layout_blocks: [\n (\n name: \"root\",\n parent: \"\",\n hook: Hook(parent_anchor: TM, self_anchor: TM),\n offset: Vec2(x: 0.0, y: 40.0),\n render_anti_criteria: [Progress],\n params: NotificationBlock((\n monitor: 0,\n border_width: 0,\n border_rounding: 8,\n background_color: Color(hex: \"#99000000\"),\n border_color: Color(hex: \"#99000000\"),\n border_color_low: Color(hex: \"#99000000\"),\n border_color_critical: Color(hex: \"#99000000\"),\n border_color_paused: Color(hex: \"#99000000\"),\n gap: Vec2(x: 0.0, y: 12.0),\n notification_hook: Hook(parent_anchor: BL, self_anchor: TL),\n )),\n ),\n\n (\n name: \"image\",\n parent: \"root\",\n hook: Hook(parent_anchor: TL, self_anchor: TL),\n offset: Vec2(x: 0.0, y: 0.0),\n params: ImageBlock((\n image_type: Hint,\n padding: Padding(left: 6.0, right: 2.0, top: 6.0, bottom: 6.0),\n rounding: 6.0,\n scale_width: 64,\n scale_height: 64,\n filter_mode: Lanczos3,\n )),\n ),\n\n (\n name: \"summary\",\n parent: \"image\",\n hook: Hook(parent_anchor: MR, self_anchor: BL),\n offset: Vec2(x: 0.0, y: 0.0),\n params: TextBlock((\n text: \"%s\",\n font: \"Arial Bold 11\",\n ellipsize: End,\n color: Color(hex: \"#F3F3F3\"),\n color_hovered: Color(hex: \"#DEDEDE\"),\n padding: Padding(left: 8.0, right: 8.0, top: 6.0, bottom: 2.0),\n dimensions: (width: (min: 280, max: 280), height: (min: 0, max: 0)),\n )),\n ),\n\n (\n name: \"body\",\n parent: \"summary\",\n hook: Hook(parent_anchor: BL, self_anchor: TL),\n offset: Vec2(x: 0.0, y: -3.0),\n params: ScrollingTextBlock((\n text: \"%b\",\n font: \"Arial 11\",\n color: Color(hex: \"#F3F3F3\"),\n color_hovered: Color(hex: \"#DEDEDE\"),\n padding: Padding(left: 8.0, right: 8.0, top: 2.0, bottom: 6.0),\n width: (min: 150, max: 250),\n scroll_speed: 0.1,\n lhs_dist: 35.0,\n rhs_dist: 35.0,\n scroll_t: 1.0,\n )),\n ),\n\n (\n name: \"rootProgress\",\n parent: \"\",\n hook: Hook(parent_anchor: MM, self_anchor: MM),\n offset: Vec2(x: 0.0, y: 0.0),\n render_criteria: [Progress],\n params: NotificationBlock((\n monitor: 0,\n border_width: 0,\n border_rounding: 8,\n background_color: Color(hex: \"#99000000\"),\n border_color: Color(hex: \"#99000000\"),\n gap: Vec2(x: 0.0, y: 12.0),\n notification_hook: Hook(parent_anchor: BL, self_anchor: TL),\n )),\n ),\n (\n name: \"progressBlock\",\n parent: \"rootProgress\",\n hook: Hook(parent_anchor: TM, self_anchor: TM),\n offset: Vec2(x: 0.0, y: 0.0),\n params: ProgressBlock((\n padding: Padding(left: 12.0, right: 12.0, top: 12.0, bottom: 12.0),\n border_width: 0.0,\n border_rounding: 10.0,\n fill_rounding: 10.0,\n border_color: Color(hex: \"#F3F3F3\"),\n background_color: Color(hex: \"#99000000\"),\n fill_color: Color(hex: \"#F3F3F3\"),\n width: 276.0,\n height: 20.0,\n border_color_hovered: Color(hex: \"#F3F3F3\"),\n background_color_hovered: Color(hex: \"#99000000\"),\n fill_color_hovered: Color(hex: \"#F3F3F3\"),\n )),\n ),\n (\n name: \"progressSummary\",\n parent: \"progressBlock\",\n hook: Hook(parent_anchor: TM, self_anchor: BM),\n offset: Vec2(x: 0.0, y: 0.0),\n params: TextBlock((\n text: \"%s\",\n ellipsize: NoEllipsize,\n font: \"Arial Bold 11\",\n color: Color(hex: \"#F3F3F3\"),\n color_hovered: Color(hex: \"#DEDEDE\"),\n padding: Padding(left: 0.0, right: 0.0, top: 6.0, bottom: 12.0),\n dimensions: (width: (min: 0, max: 300), height: (min: 0, max: 0)),\n )),\n ),\n \n (\n name: \"progressBody\",\n parent: \"progressBlock\",\n hook: Hook(parent_anchor: BM, self_anchor: TM),\n offset: Vec2(x: 0.0, y: 0.0),\n params: TextBlock((\n text: \"%b\",\n font: \"Arial 11\",\n ellipsize: NoEllipsize,\n color: Color(hex: \"#F3F3F3\"),\n color_hovered: Color(hex: \"#DEDEDE\"),\n padding: Padding(left: 0.0, right: 0.0, top: 12.0, bottom: 6.0),\n dimensions: (width: (min: 0, max: 300), height: (min: 0, max: 0)),\n )),\n ),\n ],\n)\n","_type":"code","_key":"0a10a159c441"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"00c93d5dd029"}],"_type":"block","_key":"263d6cdac4cd"},{"language":"perl","filename":"vol.sh","code":"#!/usr/bin/env perl\n\n## The sink should be the default\nmy $sink = `pactl get-default-sink`;\n\n## Run pactl and store output \nopen(my $fh, '-|', 'pactl list sinks');\n\n## Set the record separator to consecutive newlines (same as -000)\n$/=\"\\n\\n\";\n\nwhile (<$fh>) {\n if (/Name:.$sink/) {\n ## Extract the current volume\n /Volume:.*?(\\d+)%/;\n my $volume=$1;\n ## Send the notification, using gdbus so we can specify the \n ## ID to update on repeat\n exec \"gdbus call --session --dest org.freedesktop.Notifications --object-path /org/freedesktop/Notifications --method org.freedesktop.Notifications.Notify 'identifier' '999' '' 'Volume' '$volume%' '[]' '{\\\"value\\\": <$volume>}' '4000'\";\n }\n}\n","_type":"code","_key":"007c5c3580f3"}],"_type":"post","_rev":"3GUDmcZdXMS7XYzeGYlZyU","_id":"782b72de-a6fd-4a59-b5c4-7d4f01404b7a"},{"views":1185,"title":"DSLR Cameras as Webcams on Linux","tags":[{"title":"Linux","slug":{"current":"linux","_type":"slug"},"_id":"f5ced506-6b69-4557-b4e8-819845089b42"},{"title":"Guides","slug":{"current":"guides","_type":"slug"},"_id":"4501a332-2a0c-4baf-8281-bf59862a250d"}],"slug":{"current":"use-a-dslr-camera-as-a-webcam-on-linux","_type":"slug"},"numberOfCharacters":3082,"headings":[{"typeLevel":2,"children":[],"key":"51c73aaab28c","text":"Setup","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"1444b0364634","text":"Usage","type":"h2","parent":null}],"estimatedWordCount":616,"estimatedReadingTime":5,"desc":"Using DSLR or Mirrorless cameras as 'webcams' on Linux thanks to v4l2","date":"2022-04-13","body":[{"style":"normal","markDefs":[],"children":[{"text":"After a few months of remote work I got fed up with my computer's terrible webcam. Without the perfect lighting everything's a blurry mess, and it constantly failed to actually be detected by Zoom correctly. If you're similarly frustrated, and happen to have a DSLR or Mirrorless camera laying around that supports USB previews, and use Arch Linux, and have a bit of patience to poke around in the command-line, then wow, this is the perfect guide for you! :)","marks":[],"_type":"span","_key":"ee91eb4cfd01"}],"_type":"block","_key":"16a28420ee06"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"337f80d5cddd"}],"_type":"block","_key":"bf373668541b"},{"style":"normal","markDefs":[],"children":[{"text":"I'll quickly detail here how I got my Canon 200D working as a \"webcam\" on my Arch Linux setup. After the initial tinkering, it's been a pretty flawless experience, and besides a few short mentions, I couldn't find any comprehensive walkthrough of these steps online.","marks":[],"_type":"span","_key":"2a198fec5473"}],"_type":"block","_key":"204903df2589"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"d2eca918d743"}],"_type":"block","_key":"1c00a4364ccb"},{"style":"h2","markDefs":[],"children":[{"text":"Setup","marks":[],"_type":"span","_key":"3e4f9fd757bf"}],"_type":"block","_key":"51c73aaab28c"},{"style":"normal","markDefs":[],"children":[{"text":"Make sure you've got a relatively recent kernel installed - I've tested this setup with major versions above 5.15.x and they all seem to work fine.","marks":[],"_type":"span","_key":"a39b27b1b0fa"}],"_type":"block","_key":"0868b7ead0e9"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"5c8726a8b196"}],"_type":"block","_key":"ba82be411ed4"},{"style":"normal","markDefs":[],"children":[{"text":"First up, install the ","marks":[],"_type":"span","_key":"192fa8f33686"},{"text":"linux-headers","marks":["code"],"_type":"span","_key":"b7d5f6b5bf28"},{"text":" package using pacman or your favourite AUR helper, if you don't already have it. These are needed in order to build kernel modules; we'll need them for v4l2. Note that if you're using a custom kernel, such as Xanmod or Zen, you'll need to install the headers for it instead (e.g. ","marks":[],"_type":"span","_key":"0782f1066ea4"},{"text":"linux-xanmod-headers","marks":["code"],"_type":"span","_key":"d2b79bf467f0"},{"text":").","marks":[],"_type":"span","_key":"286012e204a5"}],"_type":"block","_key":"6533e0884a10"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"8a33e099af48"}],"_type":"block","_key":"3971c5ec7848"},{"style":"normal","markDefs":[],"children":[{"text":"After the headers are installed, install the ","marks":[],"_type":"span","_key":"073a51d5e4f1"},{"text":"v4l2loopback-dkms","marks":["code"],"_type":"span","_key":"3775ac93645d"},{"text":" package from the AUR. Then, ensure it's loaded using ","marks":[],"_type":"span","_key":"5ff29bccb0f4"},{"text":"modprobe","marks":["code"],"_type":"span","_key":"b61fd7db2d3b"},{"text":" - A good idea is to also add an entry to ","marks":[],"_type":"span","_key":"4bc476af0c50"},{"text":"/etc/modules-load.d","marks":["code"],"_type":"span","_key":"61c8ec80719a"},{"text":" so it's always loaded automatically at boot.","marks":[],"_type":"span","_key":"c30de5429a07"}],"_type":"block","_key":"abffb5580abb"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"b329b2eeb337"}],"_type":"block","_key":"8151691c570d"},{"style":"normal","markDefs":[],"children":[{"text":"Next, we can list all video devices using ","marks":[],"_type":"span","_key":"5ac6b39568fe"},{"text":"v4l2-ctl","marks":["code"],"_type":"span","_key":"ee7f1db919fe"},{"text":" - You should see something like '","marks":[],"_type":"span","_key":"62f87c65ea12"},{"text":"Dummy video device (0x0000)","marks":["code"],"_type":"span","_key":"37ed690120a5"},{"text":"', and a ","marks":[],"_type":"span","_key":"bc953326f15d"},{"text":"/dev/","marks":["code"],"_type":"span","_key":"3bf554919f4f"},{"text":" path:","marks":[],"_type":"span","_key":"fc2563bdf5ef"}],"_type":"block","_key":"d4056d510484"},{"language":"bash","highlightedLines":[1,2],"code":"$ v4l2-ctl --list-devices\n\nDummy video device (0x0000) (platform:v4l2loopback-000):\n /dev/video0","_type":"code","_key":"b8686161df5b"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"d13ffe91b889"}],"_type":"block","_key":"55fb6c34ed29"},{"style":"normal","markDefs":[],"children":[{"text":"Yay! That means the module's loaded properly. Next up, we need to install ","marks":[],"_type":"span","_key":"f13d6d6605e0"},{"text":"gphoto2","marks":["code"],"_type":"span","_key":"bd010be4078a"},{"text":" in order to snag the camera's preview output and pipe it to that ","marks":[],"_type":"span","_key":"f80f3dc80718"},{"text":"/dev/video0/","marks":["code"],"_type":"span","_key":"e597a97b06e8"},{"text":" path, using ","marks":[],"_type":"span","_key":"5221c54de594"},{"text":"ffmpeg","marks":["code"],"_type":"span","_key":"40a8d7ea2059"},{"text":".","marks":[],"_type":"span","_key":"8e18b5ab15a1"}],"_type":"block","_key":"241ceda6605a"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"cda1d43b97d2"}],"_type":"block","_key":"654d58f6ecdc"},{"style":"normal","markDefs":[],"children":[{"text":"After installing the ","marks":[],"_type":"span","_key":"7c821b702605"},{"text":"gphoto2","marks":["code"],"_type":"span","_key":"3042363055c2"},{"text":" package from the AUR, connect your camera via USB, and check the output of ","marks":[],"_type":"span","_key":"9e90909cdfd6"},{"text":"gphoto2 --auto-detect","marks":["code"],"_type":"span","_key":"bd40040380a5"},{"text":" - it should look something like this:","marks":[],"_type":"span","_key":"0aa10dbaaab1"}],"_type":"block","_key":"ca521b080225"},{"language":"bash","code":"$ gphoto2 --auto-detect\n\nModel Port\n----------------------------------------------------------\nCanon EOS 200D usb:009,013","_type":"code","_key":"ececdf230dcd"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"45891b9e3ae2"}],"_type":"block","_key":"5806a0327cce"},{"style":"h2","markDefs":[],"children":[{"text":"Usage","marks":[],"_type":"span","_key":"f372b3db96f5"}],"_type":"block","_key":"1444b0364634"},{"style":"normal","markDefs":[],"children":[{"text":"The final step is to put together a one-liner script to take ","marks":[],"_type":"span","_key":"ef6ccd8d6fdd"},{"text":"gphoto2","marks":["code"],"_type":"span","_key":"6c5b61a7801f"},{"text":"'s preview and pipe that to the dummy video device ","marks":[],"_type":"span","_key":"879f97b9fecb"},{"text":"v4l2","marks":["code"],"_type":"span","_key":"14a8f137d35d"},{"text":" has created for us - make sure to check the exact ","marks":[],"_type":"span","_key":"23c5f8c81cfd"},{"text":"/dev/","marks":["code"],"_type":"span","_key":"991f5f98f5b2"},{"text":" path from earlier, yours may not be ","marks":[],"_type":"span","_key":"c04130523ffb"},{"text":"video0","marks":["code"],"_type":"span","_key":"f1b6c40f5069"},{"text":". Something like this:","marks":[],"_type":"span","_key":"6fdd75230b13"}],"_type":"block","_key":"803f79ff1bc3"},{"language":"bash","code":"$ gphoto2 --stdout --capture-movie | ffmpeg -i - -vcodec rawvideo -pix_fmt yuv420p -threads 0 -f v4l2 /dev/video0","_type":"code","_key":"e22ca1124d20"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"30f1caf9cccb"}],"_type":"block","_key":"637fb0bc9895"},{"style":"normal","markDefs":[],"children":[{"text":"Since ","marks":[],"_type":"span","_key":"c4178b675271"},{"text":"ffmpeg","marks":["code"],"_type":"span","_key":"1885250cf609"},{"text":" is handling the stream's encoding, we can take advantage of any of its CLI options, e.g., limiting the frame rate to lower CPU usage, or applying filters to the video.","marks":[],"_type":"span","_key":"801646e85042"}],"_type":"block","_key":"b25d2c86d933"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"f25c21544678"}],"_type":"block","_key":"9284eb793634"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://github.com/kiosion/dotfiles","external":true,"_type":"link","_key":"474a5f8fb927"}],"children":[{"text":"So, what's a good way to permanently use this setup? I personally don't mind a bit of jank in my setup, so I currently just have a script living in ","marks":[],"_type":"span","_key":"55923f56641b"},{"text":"/usr/bin","marks":["code"],"_type":"span","_key":"505aad8bb31f"},{"text":" that runs the initial command to start piping the video output to ","marks":[],"_type":"span","_key":"a384fef00057"},{"text":"/dev/video0","marks":["code"],"_type":"span","_key":"89bbcb16610e"},{"text":", and to attempt to restart on any failures. I'll leave a link to it in my ","marks":[],"_type":"span","_key":"86dad67a9c78"},{"text":"dotfiles github repo","marks":["474a5f8fb927"],"_type":"span","_key":"6acf0d05b08c"},{"text":". This script is then added to my ","marks":[],"_type":"span","_key":"fbda8e8a70d7"},{"text":"bspwmrc","marks":["code"],"_type":"span","_key":"efff85b1a35d"},{"text":"'s autostart section to run every login, although you could also run it manually in a new shell only when you want to use your webcam.","marks":[],"_type":"span","_key":"a679c79ba997"}],"_type":"block","_key":"20f44aeef19b"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"aadf0ad5d088"}],"_type":"block","_key":"09afb87a9dae"},{"style":"normal","markDefs":[],"children":[{"text":"That's all there is to it, though! Feel free to reach out if you have any issues getting this working, I've spent a while before troubleshooting so may have an idea of where to start.","marks":[],"_type":"span","_key":"5ef81237545c"}],"_type":"block","_key":"74c0b3101410"}],"_type":"post","_rev":"OV3o2t7M68aAVZSgGazqHz","_id":"3ebfef98-d00a-446f-b04e-c7a16087f51a"},{"views":1951,"title":"Using a Yubikey for SSH Authentication on MacOS / Linux","tags":[{"title":"Security","slug":{"current":"security","_type":"slug"},"_id":"ed0209e3-6521-43aa-96a7-215752a388e1"},{"title":"SSH","slug":{"current":"ssh","_type":"slug"},"_id":"5b159683-cef1-40af-8e1d-95e04e23aaf4"},{"title":"Guides","slug":{"current":"guides","_type":"slug"},"_id":"4501a332-2a0c-4baf-8281-bf59862a250d"}],"slug":{"current":"using-a-yubikey-for-seamless-ssh-authentication","_type":"slug"},"numberOfCharacters":4973,"headings":[{"typeLevel":2,"children":[{"typeLevel":3,"children":[],"key":"368fead78fb7","text":"Linux","type":"h3","parent":"aeae72dc7061"},{"typeLevel":3,"children":[],"key":"24dcbf0339bd","text":"MacOS","type":"h3","parent":"aeae72dc7061"}],"key":"aeae72dc7061","text":"Setup","type":"h2","parent":null},{"typeLevel":2,"children":[{"typeLevel":3,"children":[{"typeLevel":4,"children":[],"key":"eb9eae6fa7b7","text":"Using yubikey-agent*","type":"h4","parent":"4fa3654ccf3b"},{"typeLevel":4,"children":[],"key":"9b9ce13893a0","text":"Using yubikey-manager","type":"h4","parent":"4fa3654ccf3b"}],"key":"4fa3654ccf3b","text":"Generate a new key","type":"h3","parent":"e09de0e076cd"},{"typeLevel":3,"children":[{"typeLevel":4,"children":[],"key":"ca8b7a7a87e4","text":"Fish","type":"h4","parent":"0c9b22df7c7c"},{"typeLevel":4,"children":[],"key":"f46695bea413","text":"Bash / ZSH / SH","type":"h4","parent":"0c9b22df7c7c"}],"key":"0c9b22df7c7c","text":"Configure your shell","type":"h3","parent":"e09de0e076cd"},{"typeLevel":3,"children":[],"key":"ff50a1a4a6d5","text":"Extra dependencies","type":"h3","parent":"e09de0e076cd"}],"key":"e09de0e076cd","text":"Steps","type":"h2","parent":null},{"typeLevel":2,"children":[],"key":"0a8240bb84b2","text":"More","type":"h2","parent":null}],"estimatedWordCount":995,"estimatedReadingTime":8,"desc":"How to authenticate SSH connections using your Yubikey's Authentication slot, on both Linux and MacOS.","date":"2021-11-29","body":[{"style":"normal","markDefs":[],"children":[{"text":"Setting up a Yubikey for SSH authentication can be a bit tricky, and I found that a lot of the existing guides out there were lacking, so I decided to write up my own to make things easier for others attempting this. ","marks":[],"_type":"span","_key":"eeee6482ecc70"}],"_type":"block","_key":"7d6be87da6e8"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://github.com/FiloSottile/yubikey-agent","external":true,"_type":"link","_key":"ce4aaf38ee71"}],"children":[{"text":"From my research, most guides focus on using the Smart Card slot for GPG. But honestly, that's overkill and can be a bit of a hassle. Luckily, with ","marks":[],"_type":"span","_key":"18825785145e"},{"text":"yubikey-agent","marks":["ce4aaf38ee71"],"_type":"span","_key":"ca08c91be711"},{"text":", we can use the Authentication slot (9a) and keep the Smart Card slot open for other uses.","marks":[],"_type":"span","_key":"c2d311a678ed"}],"_type":"block","_key":"52176bfa6c1e"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"1a3f18e96ac3"}],"_type":"block","_key":"9153802bdfd5"},{"style":"h2","markDefs":[],"children":[{"text":"Setup","marks":[],"_type":"span","_key":"5686f2b29755"}],"_type":"block","_key":"aeae72dc7061"},{"style":"h3","markDefs":[],"children":[{"text":"Linux","marks":[],"_type":"span","_key":"b61498c47bec"}],"_type":"block","_key":"368fead78fb7"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://www.yubico.com/support/download/yubikey-manager/","external":true,"_type":"link","_key":"2252185d8e12"}],"children":[{"text":"yubikey-manager","marks":["code"],"_type":"span","_key":"e1239dbee18a"},{"text":" can be used as either an AppImage from ","marks":[],"_type":"span","_key":"3e6f11d8137d"},{"text":"Yubikey's website","marks":["2252185d8e12"],"_type":"span","_key":"debe7378f0841"},{"text":" or installed from your package manager.","marks":[],"_type":"span","_key":"debe7378f0842"}],"_type":"block","_key":"c78012777849"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://archlinux.org/packages/community/x86_64/yubikey-manager-qt/","external":true,"_type":"link","_key":"9956a5c6d19b"},{"newtab":true,"href":"https://archlinux.org/packages/community/x86_64/yubikey-manager/","external":true,"_type":"link","_key":"aebc6531f26d"}],"listItem":"bullet","level":1,"children":[{"text":"On Arch Linux, it's available under the name ","marks":[],"_type":"span","_key":"a902decf6e8e"},{"text":"yubikey-manager-qt","marks":["9956a5c6d19b","code"],"_type":"span","_key":"ced246c3ffaa1"},{"text":"; ","marks":[],"_type":"span","_key":"ced246c3ffaa2"},{"text":"yubikey-manager","marks":["aebc6531f26d","code"],"_type":"span","_key":"ced246c3ffaa3"},{"text":" for the CLI version (","marks":[],"_type":"span","_key":"ced246c3ffaa4"},{"text":"paru/yay -S yubikey-manager-qt","marks":["code"],"_type":"span","_key":"ced246c3ffaa5"},{"text":").","marks":[],"_type":"span","_key":"ced246c3ffaa6"}],"_type":"block","_key":"375bceca7ded"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://packages.ubuntu.com/search?suite=default§ion=all&arch=any&keywords=yubikey-manager-qt&searchon=names","external":true,"_type":"link","_key":"61f37da02bd9"},{"newtab":true,"href":"https://packages.ubuntu.com/search?suite=default§ion=all&arch=any&keywords=yubikey-manager&searchon=names","external":true,"_type":"link","_key":"9b4bfc372936"}],"listItem":"bullet","level":1,"children":[{"text":"On Ubuntu, it's also available under the name ","marks":[],"_type":"span","_key":"410e4e4c3f8f"},{"text":"yubikey-manager-qt","marks":["61f37da02bd9","code"],"_type":"span","_key":"af84a81ce4171"},{"text":"; ","marks":[],"_type":"span","_key":"af84a81ce4172"},{"text":"yubikey-manager","marks":["9b4bfc372936","code"],"_type":"span","_key":"af84a81ce4173"},{"text":" for the CLI version (","marks":[],"_type":"span","_key":"af84a81ce4174"},{"text":"sudo apt-get install yubikey-manager-qt","marks":["code"],"_type":"span","_key":"af84a81ce4175"},{"text":").","marks":[],"_type":"span","_key":"af84a81ce4176"}],"_type":"block","_key":"9ed1bd24e479"},{"style":"normal","markDefs":[],"children":[{"text":"After installation, ","marks":[],"_type":"span","_key":"fd167fadb3fe"},{"text":"pcscd.service","marks":["code"],"_type":"span","_key":"c599ef8538551"},{"text":" needs to be enabled and started: ","marks":[],"_type":"span","_key":"c599ef8538552"},{"text":"sudo systemctl enable pcscd.service --now","marks":["code"],"_type":"span","_key":"c599ef8538553"},{"text":".","marks":[],"_type":"span","_key":"c599ef8538554"}],"_type":"block","_key":"616897c0cc96"},{"style":"normal","markDefs":[],"children":[{"text":"yubikey-manager","marks":["code"],"_type":"span","_key":"09a310fc2517"},{"text":" can be found under the name ","marks":[],"_type":"span","_key":"d5c87203a2de"},{"text":"ykman-gui","marks":["code"],"_type":"span","_key":"2aa512722cf31"},{"text":"; ","marks":[],"_type":"span","_key":"2aa512722cf32"},{"text":"ykman","marks":["code"],"_type":"span","_key":"2aa512722cf33"},{"text":" for the CLI version.","marks":[],"_type":"span","_key":"2aa512722cf34"}],"_type":"block","_key":"ac95e2a30a71"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"2740b4566c9a"}],"_type":"block","_key":"27f4fde326d7"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://aur.archlinux.org/packages/yubikey-agent/","external":true,"_type":"link","_key":"f844b959e866"},{"newtab":true,"href":"https://github.com/FiloSottile/yubikey-agent/blob/main/systemd.md","external":true,"_type":"link","_key":"a91049b5b99f"}],"children":[{"text":"yubikey-agent","marks":["code"],"_type":"span","_key":"d2d63d87d301"},{"text":" can be installed using the ","marks":[],"_type":"span","_key":"0b4ca6d7a7b3"},{"text":"yubikey-agent","marks":["code","f844b959e866"],"_type":"span","_key":"d62b3a511155"},{"text":" package from the AUR, or on other distros, can be ","marks":[],"_type":"span","_key":"3b7232501ba9"},{"text":"installed manually","marks":["a91049b5b99f"],"_type":"span","_key":"f19d87b02c9e"},{"text":".","marks":[],"_type":"span","_key":"7c2dadb28e92"}],"_type":"block","_key":"252d4951278c"},{"style":"normal","markDefs":[],"children":[{"text":"After installation, it needs to be enabled and started: ","marks":[],"_type":"span","_key":"e02cb07b6100"},{"text":"systemctl daemon-reload --user && systemctl --user enable yubikey-agent.service --now","marks":["code"],"_type":"span","_key":"8d05646434a1"},{"text":".","marks":[],"_type":"span","_key":"982704122de8"}],"_type":"block","_key":"728eeb653d54"},{"style":"h3","markDefs":[],"children":[{"text":"MacOS","marks":[],"_type":"span","_key":"5c8cc8bcf896"}],"_type":"block","_key":"24dcbf0339bd"},{"style":"normal","markDefs":[{"newtab":true,"href":"https://www.yubico.com/support/download/yubikey-manager/","external":true,"_type":"link","_key":"ee7badcb9e23"}],"children":[{"text":"yubikey-manager","marks":["code"],"_type":"span","_key":"bbe0fb31a4d7"},{"text":" can be downloaded and installed from ","marks":[],"_type":"span","_key":"86d66e32c601"},{"text":"Yubikey's website","marks":["ee7badcb9e23"],"_type":"span","_key":"03a827b9288c1"},{"text":".","marks":[],"_type":"span","_key":"03a827b9288c2"}],"_type":"block","_key":"2643b1965c03"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"436fd50bd6df"}],"_type":"block","_key":"0ecc9cee417b"},{"style":"normal","markDefs":[],"children":[{"text":"yubikey-agent","marks":["code"],"_type":"span","_key":"28c074b9e485"},{"text":" can be installed using Homebrew: ","marks":[],"_type":"span","_key":"10054e203197"},{"text":"brew install yubikey-agent","marks":["code","notranslate"],"_type":"span","_key":"d7fa47e862c7"},{"text":". After installation, it needs to be enabled using ","marks":[],"_type":"span","_key":"24a0e8ef1662"},{"text":"brew services start yubikey-agent","marks":["code","notranslate"],"_type":"span","_key":"ce9a8e9232e3"},{"text":".","marks":[],"_type":"span","_key":"2c7188e3d423"}],"_type":"block","_key":"1c3e1752b5c8"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"745208f446a5"}],"_type":"block","_key":"392f614031ac"},{"style":"h2","markDefs":[],"children":[{"text":"Steps","marks":[],"_type":"span","_key":"d52368b628970"}],"_type":"block","_key":"e09de0e076cd"},{"style":"h3","markDefs":[],"children":[{"text":"Generate a new key","marks":[],"_type":"span","_key":"cb98f9de28ec0"}],"_type":"block","_key":"4fa3654ccf3b"},{"style":"normal","markDefs":[],"children":[{"text":"Here, you could either choose ","marks":[],"_type":"span","_key":"ac78577f5d3c0"},{"text":"yubikey-agent -setup","marks":["code"],"_type":"span","_key":"ac78577f5d3c1"},{"text":", or, use ","marks":[],"_type":"span","_key":"ac78577f5d3c2"},{"text":"yubikey-manager","marks":["code"],"_type":"span","_key":"83dae7cc28b1"},{"text":" to generate a key. I chose the second option and recommend it, as although ","marks":[],"_type":"span","_key":"e6c9f07d3b36"},{"text":"yubikey-agent","marks":["code"],"_type":"span","_key":"af45d4bdb124"},{"text":" is easier, it doesn't give any control over the type or length of key generated.","marks":[],"_type":"span","_key":"b408b1dcd2b7"}],"_type":"block","_key":"5ce945157ef3"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"a7eb37b02676"}],"_type":"block","_key":"94fd679d53de"},{"style":"h4","markDefs":[],"children":[{"text":"Using yubikey-agent*","marks":[],"_type":"span","_key":"682085f5678a"}],"_type":"block","_key":"eb9eae6fa7b7"},{"style":"normal","markDefs":[],"children":[{"text":"To generate a new key with yubikey-agent and store it in your Yubikey's PIV authentication slot, simply run ","marks":[],"_type":"span","_key":"72c2f8fc3b21"},{"text":"yubikey-agent -setup","marks":["code"],"_type":"span","_key":"08aa32499da5"},{"text":" with your yubikey connected and follow the steps.","marks":[],"_type":"span","_key":"ea8f54308a9c"}],"_type":"block","_key":"b85408691147"},{"style":"normal","markDefs":[],"children":[{"text":"You'll be asked to set a PIN, and be given your public key once the process is finished.","marks":[],"_type":"span","_key":"84f5004f2442"}],"_type":"block","_key":"fd7fae7ef73b"},{"style":"normal","markDefs":[{"note":[{"style":"normal","markDefs":[{"newtab":true,"href":"https://github.com/FiloSottile/yubikey-agent#manual-setup-and-technical-details","external":true,"_type":"link","_key":"21c3977ec204"}],"children":[{"text":"See yubikey-agent's ","marks":[],"_type":"span","_key":"59d42b364d3f"},{"text":"manual setup instructions","marks":["21c3977ec204"],"_type":"span","_key":"a7b3ee529810"}],"_type":"block","_key":"073818b1b19b"}],"_type":"footnote","_key":"0682cfcdf8ff"}],"children":[{"text":"It's important to note that yubikey-agent -setup generates a random Management Key and stores it in PIN-protected metadata, making it difficult to use other PIV slots without some hack-y workarounds","marks":["em","0682cfcdf8ff"],"_type":"span","_key":"ea7b9b26a6f8"},{"text":".","marks":["em"],"_type":"span","_key":"c1daf5c2381c"}],"_type":"block","_key":"693db5ac0327"},{"style":"h4","markDefs":[],"children":[{"text":"Using yubikey-manager","marks":[],"_type":"span","_key":"133df66b25ce0"}],"_type":"block","_key":"9b9ce13893a0"},{"style":"normal","markDefs":[],"children":[{"text":"To generate a new key using the ","marks":[],"_type":"span","_key":"f39e6124b2f0"},{"text":"yubikey-manager","marks":["code"],"_type":"span","_key":"6f582c617253"},{"text":" software, navigate to the 'Applications > PIV' tab, and make sure the 'Authentication' slot is selected. If there's already a certificate present, ","marks":[],"_type":"span","_key":"2cd3316f8bed"},{"text":"make sure","marks":["strong"],"_type":"span","_key":"3ed0883b26261"},{"text":" it's not important and not in use. Overwriting the slot is ","marks":[],"_type":"span","_key":"3ed0883b26262"},{"text":"not","marks":["strong"],"_type":"span","_key":"3ed0883b26263"},{"text":" reversible.","marks":[],"_type":"span","_key":"3ed0883b26264"}],"_type":"block","_key":"4369522d3722"},{"style":"normal","markDefs":[],"children":[{"text":"Click 'Generate', select the key type you want to generate (the default should be fine if you're not sure), name it 'SSH Key', and set the expiration date.","marks":[],"_type":"span","_key":"8d4407485880"}],"_type":"block","_key":"7afcb2cf3f45"},{"style":"normal","markDefs":[],"children":[{"text":"If everything looks good, save it and enter the PIN to confirm. If you haven't set one previously, the default is ","marks":[],"_type":"span","_key":"7ac03f955543"},{"text":"123456","marks":["code"],"_type":"span","_key":"0c5053c6140b1"},{"text":" - This should be changed to something more secure, along with the PUK and Management Key. Save these somewhere offline and safe.","marks":[],"_type":"span","_key":"0c5053c6140b2"}],"_type":"block","_key":"e7d322b71873"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"befa25c988de"}],"_type":"block","_key":"ea0685afcb68"},{"style":"h3","markDefs":[],"children":[{"text":"Configure your shell","marks":[],"_type":"span","_key":"d5de16db2a9a0"}],"_type":"block","_key":"0c9b22df7c7c"},{"style":"normal","markDefs":[],"children":[{"text":"Next, you'll need to configure your shell to set the ","marks":[],"_type":"span","_key":"170a7cf1afff0"},{"text":"SSH_AUTH_SOCK","marks":["code"],"_type":"span","_key":"170a7cf1afff1"},{"text":" environment variable on launch.","marks":[],"_type":"span","_key":"170a7cf1afff2"}],"_type":"block","_key":"29327a5b650f"},{"style":"normal","markDefs":[],"children":[{"text":"First find the location of the yubikey-agent socket. You can look at the output of ","marks":[],"_type":"span","_key":"36c0104bfdf90"},{"text":"ps aux | grep yubikey-agent","marks":["code"],"_type":"span","_key":"36c0104bfdf91"},{"text":" if you're not sure. For me on Linux, its location was ","marks":[],"_type":"span","_key":"36c0104bfdf92"},{"text":"/run/user/{Your UID}/yubikey-agent/yubikey-agent.sock","marks":["code"],"_type":"span","_key":"36c0104bfdf93"},{"text":" by default.","marks":[],"_type":"span","_key":"36c0104bfdf94"}],"_type":"block","_key":"22313077f009"},{"style":"h4","markDefs":[],"children":[{"text":"Fish","marks":[],"_type":"span","_key":"0a7df2ceedce"}],"_type":"block","_key":"ca8b7a7a87e4"},{"style":"normal","markDefs":[],"children":[{"text":"Open your config and add ","marks":[],"_type":"span","_key":"34bff9794fea"},{"text":"set -gx SSH_AUTH_SOCK \"/run/user/{Your UID}/yubikey-agent/yubikey-agent.sock\"","marks":["code"],"_type":"span","_key":"b6ca08730ac61"},{"text":", where the path is the location of the yubikey-agent socket.","marks":[],"_type":"span","_key":"b6ca08730ac62"}],"_type":"block","_key":"3ade0f2db901"},{"style":"h4","markDefs":[],"children":[{"text":"Bash / ZSH / SH","marks":[],"_type":"span","_key":"1acf4f9f1838"}],"_type":"block","_key":"f46695bea413"},{"style":"normal","markDefs":[],"children":[{"text":"Open your config and add ","marks":[],"_type":"span","_key":"fe698b867111"},{"text":"export SSH_AUTH_SOCK=\"/run/user/{Your UID}/yubikey-agent/yubikey-agent.sock\"","marks":["code"],"_type":"span","_key":"68a87a6eec801"},{"text":", where the path is the location of the yubikey-agent socket.","marks":[],"_type":"span","_key":"68a87a6eec802"}],"_type":"block","_key":"90e4b4009f3c"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"649ab4f7a6e1"}],"_type":"block","_key":"f84e6e3862e1"},{"style":"h3","markDefs":[],"children":[{"text":"Extra dependencies","marks":[],"_type":"span","_key":"890b0874357a"}],"_type":"block","_key":"ff50a1a4a6d5"},{"style":"normal","markDefs":[],"children":[{"text":"Finally, in order to actually use the private key, you first need to authenticate with your set PIN. If you're running a distro such as Ubuntu this should work out-of-the-box, but if you're on a custom or more minimal install, you may need to install a compatible keychain and polkit agent first. I prefer GNOME's polkit agent since it displays nice-looking modals and works with archlinux-keychain, but any should work.","marks":[],"_type":"span","_key":"63e4a24c5d23"}],"_type":"block","_key":"39fd743af194"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"1580b230ad23"}],"_type":"block","_key":"f99aa593f468"},{"style":"h2","markDefs":[],"children":[{"text":"More","marks":[],"_type":"span","_key":"f669e7cbcc16"}],"_type":"block","_key":"0a8240bb84b2"},{"style":"normal","markDefs":[],"children":[{"text":"That's it! You should now have a fully configured and working SSH key in your Yubikey's Authentication slot.","marks":[],"_type":"span","_key":"a986d123f6bc0"}],"_type":"block","_key":"82aff99aa3b5"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"To print the public key and test the setup, run ","marks":[],"_type":"span","_key":"02c1e623ca650"},{"text":"ssh-add -L","marks":["code"],"_type":"span","_key":"02c1e623ca651"},{"text":".","marks":[],"_type":"span","_key":"02c1e623ca652"}],"_type":"block","_key":"48f9ad7b7310"},{"style":"normal","markDefs":[],"listItem":"bullet","level":2,"children":[{"text":"If you don't see any identities, or get an error, double-check all the required services are installed and running, and that you've configured your shell's SSH_AUTH_SOCK environment variable correctly.","marks":[],"_type":"span","_key":"0aea37dca7090"}],"_type":"block","_key":"19a0a3ed6e9e"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"If not using the '-setup' flag with ","marks":[],"_type":"span","_key":"8584732dee850"},{"text":"yubikey-agent","marks":["code"],"_type":"span","_key":"2fde87a57772"},{"text":", ","marks":[],"_type":"span","_key":"78aac3ae798f"},{"text":"make sure","marks":["em"],"_type":"span","_key":"8584732dee851"},{"text":" you set a secure PIN, PUK, and Management Key and store them somewhere safe and offline.","marks":[],"_type":"span","_key":"8584732dee852"}],"_type":"block","_key":"9ef3612f7a9d"},{"style":"normal","markDefs":[],"listItem":"bullet","level":1,"children":[{"text":"If you run into issues using the Yubikey for other functionality after using it with yubikey-agent, I've found either unplugging-and-re-plugging it, or sending a SIGHUP to the ","marks":[],"_type":"span","_key":"35c0d1712ea00"},{"text":"yubikey-agent","marks":["code"],"_type":"span","_key":"9d342fd09753"},{"text":" process solves this.","marks":[],"_type":"span","_key":"d3e4bae56f6e"}],"_type":"block","_key":"997becf55834"},{"style":"normal","markDefs":[],"children":[{"text":"","marks":[],"_type":"span","_key":"ddc651e378af"}],"_type":"block","_key":"7d60710acb03"}],"_type":"post","_rev":"OV3o2t7M68aAVZSgGfnAup","_id":"354f9086-ce6f-47f1-8839-77d6f3491ade"}],"meta":{"total":8,"sort":"date","order":"desc","count":8,"syncTags":["s1:Us+0EQ","s1:76AoNQ","s1:8hOdmg","s1:3gb18g","s1:5a/gNA","s1:Chv5AQ","s1:atII2A","s1:NhVsyw","s1:1wiuxw","s1:wCesqw","s1:7jA3yQ","s1:dfaY3A","s1:idlGQQ","s1:Wcxt3A","s1:HsMr2w","s1:kKQjrw"],"ms":0}}

Maxim Dietz

Using a Yubikey for SSH Authentication on MacOS / Linux