Skip to main content

the avatar of Federico Mena-Quintero

Some thoughts on linking to code

I have been updating the text layout roadmap for librsvg, and part of this involves describing how some of the current code works — for example, how a <text> element gets broken up into a tree of Chunk and Span structures.

Notice how those links go to the generated documentation for the library's internals. In the HTML, rustdoc adds "source" links that in turn take you to the actual source code for that item.

Aside: Chunk has documentation, but Span doesn't; I haven't gotten around to writing it yet. Linking to the documentation for the library's internals helps me see what things are undocumented yet. Maybe a struct Point { x: f64, y: f64 } doesn't need much documetation, but something more complicated like Span definitely does!

Another way of linking to these items would be to link to the actual source for Chunk and Span. Those links go to the HTML version of the source code in GitLab, for a specific commit.

For example, the link to Chunk is https://gitlab.gnome.org/GNOME/librsvg/-/blob/4cd62ad9/src/text.rs#L48-66 and it breaks down like this:

  • gitlab.gnome.org - the server, obviously
  • GNOME - group name
  • librsvg - project name
  • blob/4cd62ad9 - prefix of the git commit id
  • src/text.rs#L48-66 - the file in the librsvg source tree, plus a fragment identifier so that GitLab will highlight a range of source lines.

Obtaining that link takes a bit of work:

  • Go to the project page. Navigate down to the file you want. (Tip: hit t and start typing the filename; you'll get an autocompletion list.)

  • If you are in the wrong branch, change it at the top of the page. Note that the URL is something like .../blob/main/src/my_file.txt

  • Click on the Permalink button near the top of the page. This changes the URL to the actual latest commit id, i.e. blob/123abc/src/...

  • Go to the lines to which you want to link. Click on the first line's number, Shift-click on the second line's number. This changes the URL to a range of lines, with a fragment identifier like #L12-34.

I generally do that when writing descriptions that refer to source lines in specific revisions. Of course, if the code changes, the description may need updating if it's a "permanent" document — but at least there are hopefully never broken links, or links to source code that no longer matches the description.

The first method — linking to the documentation for the library's internals — has the advantage of being actual documentation, with a link to the source code as a bonus. I would probably prefer it if rustdoc generated links to GitLab's display of sources, instead of generating its own embedded copy of the source code, but it's not a big deal.

The second method, linking to specific revisions in GitLab's source view, is perhaps more direct when you want the reader to see the source code immediately, but it's not as easy to navigate. The reader has to read the source and there is no way in GitLab to easily jump to symbol definitions, for example, or to find the implementations for a struct's methods. The generated rustdoc has all that.

Finally, in real-time conversation, I may just link to the blob/main URLs for whatever the latest revision is at the time. I expect my interlocutor to look at the link basically immediately, or really soon after our conversation, so it will show the same context as I was thinking about.

I suppose each method has its place:

  • Link to the generated documentation for the source code — Friendly to the reader if they need more context; good for high-level exploration. Links can go out of date if you rename symbols (we don't store generated docs for each revision).

  • Link to blob/123abc or a specific revision — unambiguous, good for descriptions of code at a specific point in time, and the reader can easily cut&paste that commit id to the git command line or other tooling.

  • Link to blob/main or the latest revision in some branch — easy to do; only takes the GitLab dance to find the line numbers. Good for casual conversation. May remain current for a long time in "permanent" documentation if you are describing code very generally and that code doesn't change a lot.

the avatar of Nathan Wolf

the avatar of Nathan Wolf

Linux Saloon in 2023

Linux Saloon, the Tux Digital online Linux User Group, is returning for a live show on the 14th of January and I am quite excited for it. In an effort to improve things a bit. I have taken the time to better focus my organization effort of the show. I have set up a public […]
a silhouette of a person's head and shoulders, used as a default avatar

Syslog-ng 101, part 4: Configuration and testing

This is the fourth part of my syslog-ng tutorial. I hope that since the previous part of my tutorial, you successfully installed syslog-ng. In this part we will finally work with syslog-ng, not just learn about the theoretical background. We will do basic configuration and testing.

You can watch the video on YouTube:

Or you can read the rest the tutorial as a blog at: https://www.syslog-ng.com/community/b/blog/posts/syslog-ng-101-part-4-configuration-and-testing

syslog-ng logo

the avatar of openSUSE News

openSUSE Conference Call for Papers is Open

The call for papers for openSUSE Conference 2023 is open!

The openSUSE Conference 2023 is scheduled to take place May 26 to May 28. The call for papers will close on April 9, which leaves 89 days to submit a talk.

The conference already has two sponsors with Fedora and SUSE. Companies interested in sponsoring the event can view sponsorship information on the project’s wiki page.

Presentations can be submitted for the following length of time:

  • Lightning Talk (10 mins)
  • Short Talk (30 mins)
  • Virtual Talk (30 mins)
  • Long Talk (45 mins)
  • Workshop (1 hour)
  • Virtual Workshop (1 hour)

The following tracks are listed for the conference:

  • Cloud and Containers
  • Community
  • Embedded Systems and Edge Computing
  • New Technologies
  • Open Source
  • openSUSE

The conference already has two sponsors with Fedora and SUSE. Companies interested in sponsoring the event can view the sponsorship prospectus on the project’s wiki page.

Volunteers who would like to help the Program Committee and/or the Organizing Team can email ddemaio@opensuse.org or attend normally scheduled community meetings. Check the notes for details.

The music festival Rock im Park will take place a week after the conference. Attendees for the conference are encouraged to book their hotel as soon as possible. Most Rock im Park visitors do not come the week earlier, but booking a hotel in advance is always recommended.

the avatar of openSUSE Heroes

Fixed security issue that affected tsp.opensuse.org

Hi,

We were contacted by Lukas Euler from Positive Security, to inform us that Travel Support Program (TSP), the application we use to reimburse the costs of traveling to events where you can promote or are organized by the project, had a significant security flaw that impacted our and others' production systems. We have since patched the vulnerability, contacted other organizations that also use the software, and have spent some time and wrote a script to parse logs, in order to asses the impact. Over the span of the last 2 years, the flaw has not been abused, outside of a script written by Lukas, which read contents of the production database via brute force.

The what & the how

In essence, the flaw allowed an attacker to see if any arbitrary string is in the database by detecting size of a response to a request with a query containing the string, table by table. Let me illustrate:

Observe the following requests:

"GET /events.json?q[end_date_gteq]=0&q[name_eq]=Open Mainframe Summit&q[requests_comments_body_cont]=a HTTP/1.1" 200 516
"GET /events.json?q[end_date_gteq]=0&q[name_eq]=Open Mainframe Summit&q[requests_comments_body_cont]=aa HTTP/1.1" 200 12
  • /events.json is our public api endpoint containing all the events ever created on the instance
  • end_date_gteq means match to end_date greater or equal to what is after the equals sign
  • name_eq means match to name equal (not case sensitive) to what is after the equals sign
  • requests_comments_body_cont means all the comment bodies that contain what is after the equals sign in all the requests that were created

As you can see, the two requests have wildly different response sizes (last number), the one with 516B returned a body containing the details of the event, while the second one with 12B did not, because no comment body in any request associated with that event matched string 'aa'. Since every reimbursement request has to have an event that is attached to it, you could find contents of every comment in the database if you spent the time going through every character one by one. Of course, the comments are the least of our worry in an application that deals with addresses and bank information. Bank information is attached to a reimbursement, which is mapped directly onto a request, so that's easy enough to find. You could find users through any object created by them, comments, reimbursements, requests, and from there you have an easy time getting to address information.

The why

By default the Ransack library that we use for querying various objects in the frontend allows for querying any association of those objects. We didn't limit the scope of association or columns that could be accessed by it. Since all the objects within the database of TSP are associated in some way or another, that gave just anybody access to the entire database.

Here's some documentation on the subject:
https://activerecord-hackery.github.io/ransack/going-further/associations/
https://activerecord-hackery.github.io/ransack/getting-started/search-matches/

And the way to fix the scopes that ransack can access:
https://activerecord-hackery.github.io/ransack/going-further/other-notes/#authorization-allowlistingdenylisting

How we fixed it:
https://github.com/openSUSE/travel-support-program/commit/d22916275c51500b4004933ff1b0a69bc807b2b7

Github Advisory:
https://github.com/openSUSE/travel-support-program/security/advisories/GHSA-2wwv-c6xh-cf68

Huge thanks to Lukas and the Positive Security team for letting us know about this, we wouldn't have known about this without you, and our data would have been in jeopardy.

the avatar of Nathan Wolf

Ender3 Ikea Lack Table Printer Enclosure

The Ender3 is seemingly a fantastic, inexpensive, entry level machine to get you started in the wondrous world of 3D printing. I would hardly call it the most quality, feature-rich machines out there but the incredible affordability is what makes is a great starting place. This wasn’t the first 3D printer I became familiar with […]

a silhouette of a person's head and shoulders, used as a default avatar

openSUSE Tumbleweed – Review of the week 2023/01

Dear Tumbleweed users and hackers,

Almost 2% of 2023 is already behind us. Week 1 is, from experience, always a still rather quiet week. Many contributors are still with their families or are just stretching some vacation. But, of course, only ‘many’ and by far not all. Tumbleweed managed to release 7 snapshots since the last review (1230, 1231, 20230101…20230105).

The main changes shipped were:

  • Qt5 qtwebengine 5.15.12
  • Mesa 22.3.2
  • xorg-x11-server 22.1.6
  • Linux kernel 6.1.2
  • Poppler 23.01.0
  • xz 5.4.0
  • ImageMagic 7.1.0.57

Staging projects start to be more filled up again, mostly with a lot of python-* updates (too many to list). The main updates sticking out are:

  • Python pytest 7.2.0
  • Meson 1.0.0
  • KDE Plasma 5.26.5
  • Linux kernel 6.1.3
  • GnuPG 2.4: breaks gpgme:qt and seahorse (fix for seahorse in the queue)
  • Libzypp 17.31.7: PackageKit fix arrived
  • Python Sphinx 6.1
  • Boost 1.81.0: breaks libetonyek and LibreOffice
  • Ruby 3.2 is being tested to become the default ruby version: YaST is failing
  • Switch to openSSL 3: tracked in Staging:N
the avatar of Zoltán Balogh

Build system statistics

From time to time we should ask ourselves how are we doing. Are we successful, are we on the right track, are we heading to the right direction, are we fast enough, are we accelerating or slowing down?

This time I am talking about the openSUSE Linux Distribution and about the SUSE Linux Enterprise Server.

And here I quickly would like to note an important disclaimer with a short story.

the avatar of Just Another Tech Blog

Group Policy on Linux

I’ve completed the first version of a book of instructions to use Samba’s client Group Policy. You can download a pdf or ebook here, purchase a print copy from Amazon, or you can read the web version. I’m only charging printing cost for the physical book (in accordance with the license). Digital copies are all free.

The purpose of the book is to provide detailed instructions to get folks up and running using Samba’s client Group Policy. I’ve received numerous requests for help on the mailing lists, and many of the questions are simple ones. Previously none of this information was documented well anywhere.

If you encounter problems getting setup, or find errors in the book, please contact me. You can also contribute to the book if you wish.