Introduction of net/http concept

[MikaeelMF]

Hi! I have written the client section for issue #2242 . I am creating a PR early and set it as a draft because I would like to hear ideas on various sections as I write each section. I would be really happy if you could read it and let me know if any ideas or points come to your mind.

[github-actions[bot]]

Dear MikaeelMF

Thank you for contributing to the Go track on Exercism! 💙 You will see some automated feedback below 🤖. It would be great if you can make sure your PR covers those points. This will save your reviewer some time and your change can be merged quicker.

• 📜 The following files usually contain very similar content.

  • concepts/<concept>/about.md
  • concepts/<concept>/introduction.md
  • exercises/concept/<exercise>/.docs/introduction.md

  Please check whether the changes you made to one of these also need to be applied to the others.

• 🧦 If you changed the function signature or the function comment in the exemplar file or the stub file (<exercise>.go), make sure the change is applied to both files.

• 🔗 If your PR fully fixes an issue, please include the text Fixes #issue_no in any line of the PR description. This will make the issue be automatically be closed when the PR is merged. If your PR is related to an existing issue but does not fix it completely, please link the issue anywhere in the description of the PR with #issue_no. You can read more about this in Github: Linking a pull request to an issue

• ✍️ If your PR is not related to an existing issue (and is not self-explaining like a typo fix), please make sure the description explains why the change you made is necessary.

• 🔤 If your PR fixes an easy to identify typo, if would be great if you could check for that typo in the whole repo. For example, if you found Unicdoe, use "replace all" in your editor (or command line magic) to fix it consistently.

Dear Reviewer/Maintainer

• 📏 Make sure you set the appropriate x:size label for the PR. (This also works after merging, in case you forgot about it.)

• 🔍 Don't be too nit-picky. If the PR is a clear improvement compared to the status quo, it should be approved as clear signal this is good to be merged even if the minor comments you might have are not addressed by the contributor. Further improvement ideas can be captured in issues (if important enough) and implemented via additional PRs.

• 🤔 After reviewing the diff in the "Files changed" section, take a moment to think about whether there are changes missing from the diff. Does something need to be adjusted in other places so the code or content stays consistent?

_{Automated comment created by PR Commenter 🤖.}

[MikaeelMF]

Currently, I am planning to break the concept introduction into two major parts. One part explains how to create HTTP clients and another how to create HTTP servers. Generally, I don't intend to get into too many details since this is only an introduction. Just enough so newcomers can get their hands dirty so they can read further upon the mentioned topics and for people who know about HTTP to get a little familiarized with what Go can offer using the net/http package. For the first part, I've decided to explain how to use the three main methods (GET, HEAD, POST) as a client. I don't have any more sections that I want to add to the client section so please let me know if you think anything can contribute to making this better.

For the server section, I have not really decided yet on what to include and what not to include. I am still doing some reading on this topic to further familiarize myself with it so I can decide on a good set of subsections to explain it well.

Also for the exercise, I am thinking about creating a backstory related to one of the previous exercises used in the roadmap but haven't really gotten into it since I first want to finish the concept introduction.

I will create a To-Do list to show the progress and will update it as I update this PR.

[MikaeelMF]

Concept introduction:

• Client:
• [x] explain client.Get
• [x] explain client.Head
• [x] explain the need to close response body
• [x] explain client.Post
• Server:
• [x] http.Server attributes (Addr, Handler, IdleTimeout, ReadHeaderTimeout, ReadTimeout)
• [x] Handlers
• [x] Multiplexers
• [x] Add the reference for the code snippet

[MikaeelMF]

Two things that I have left out are discussing Middleware and concurrency. Since middleware is a general concept and it can be written in form of handlers, I did not seem it necessary to include it in this introduction. Also on the concurrency, since it is a bit out of scope for this concept, I did not got into it.

[junedev]

@MikaeelMF I did not read the current content yet, I will need to find some more time for that. I just wanted to comment on what you wrote above regarding middleware and concurrency.

I agree middleware can be left out for now as there is no special support for this in plain Go anyway.

Regarding concurrency, I think it is important to explain in the server part that net/http creates a new Go routines for each incoming request and because of that it is totally fine to have synchronous/blocking code in an http handler. A lot of Go beginners don't understand this properly and kick off additional unnecessary go routines inside the handler.

[junedev]

You don't need configlet to change the root level config.json file, it won't do that for you anyway. You need to edit the config yourself and add the new concept to the concept array. You can generate the needed uuid with any online tool.

[MikaeelMF]

@junedev Sorry for my late response. Thank you for your point on the configlet. Regarding the concurrency, I think It can be explained for advanced users, but since the point of this introduction, as you have stated in your comment is "How to do X in language Y? (for someone that already knows X)" I thought maybe it would be out of scope because it does not have a direct impact on "how to use net/http" from an introductory point-of-view. But considering it all, it can be explained in a ~~~~exercism/advanced~~~~ section so people who already know about go routines can read it and use it in their programming.

I will update the text and add this section and will start to work on the exercise parts. For this, I think it would be interesting to continue on the story of weather-forecast exercise story. And currently, I am thinking of creating two separate exercises one for server and one for client. Of course, they will be compatible with each other.

Also I have one question regarding exercism code of conduct. Is it more appropriate if I write both concept and exercise in one PR or I should create a separate PR for the exercise part?

[junedev]

@MikaeelMF

Re concurrency Sorry, I did not make the big picture clear enough here. Imagine a future where tehre is a separate concept and exercise that teaches Goroutines (and others for the other Go concurrency primitives). Your exercise will be set up so that the student can only access it after they completed the Goroutines exercise. Your content should be written like this part already exists and when you mention Goroutines there should be a link placed to some article that explains them. Then in a couple of month when we have the Exercism content on this, we will replace the external link with the link to the internal concept. We did not want to hold you back creating the http exercise until we have all the prerequisites concepts done but you should try to act like it so thinks fit together nicely later on. So it would be great if you could write a section on how http handling works assuming the student knows what Goroutines are. I don't think it should be in an "advanced" block tbh because imo it is very important to understand these basics of how a language does this. Do you get the idea? Is that ok with you?

Re splitting server/client exercises Afaik it is not possible to have 2 exercises teach the same concept. So you have 2 options: a) If you really think teaching server + client is too much for 1 exercise, you can create two separate concepts as well and then have each exercise teach one of those concepts. b) If you think the about of content is ok for one concept, then you need to have 1 exercise with tasks for both parts. The description of the task can explain when you switching from one part to the other and also in the introduction part at the top you can tell students that tasks ... will be focused on X and ... will be focused on Y. Be aware though that you cannot add additional sub-headers to the exercise structure. They need to conform the official format so that things work out on the website (linking hints and test results to the correct task etc.).

Re PRs It is up to you how you want to handle this. Some contributors split it, some do it in one PR.

Sidenote: A Code of Conduct is a special document that explains how to behave, not processes/practices. :slightly_smiling_face: https://exercism.org/docs/using/legal/code-of-conduct

[MikaeelMF]

@junedev Sorry for my misunderstanding. I have written a brief section on the subject, I would really appreciate it if you could read it and let me know if it needs a more technical explanation or if what I've written is enough. On your point about having two exercises, from what I have seen in python roadmap on the website, there are several exercises for one concept. By having "two separate exercises" I meant something like that. Regarding the PR, that's great to hear! Also, thank you for your explanation about the meaning of Code of Conduct! I did not know that! 😅

[junedev]

@MikaeelMF A concept can have many practice exercises that allow the student to use the learned concept later on but a concept can only have have one learning/concept exercise that introduces/teaches that concept. If you are referring to those bubbles in the Python concept boxes, those are practice exercises. If you click on one concept, there is always one exercise to "Learn X" on the top right.

In the context of the issue you are working on, we don't consider practice exercises yet, we are referring to the one concept exercise. We can talk about creating more practice exercises later but for know we should focus on the task at hand.

I know there is a lot to learn when creating the first concept/exercise here. It also took me quite a long time to wrap my head around things when I started with that. Just continue to ask questions if something is unclear.

[MikaeelMF]

@junedev Oh, thanks for the clarification! So I will try to make things work in one exercise and see how things go. Also, thanks for your patience and helping me out! I will ask you for your advice if anything new comes up!

[MikaeelMF]

So I am at the final stages of writing this concept's exercise, I have some questions regarding how to implement some parts of it:

1. What is the difference between introduction.md vs the concept introduction.md?
2. What should be the package name for example solutions?

I would really appreciate it if I can get any help with these.

[andrerfcsantos]

What is the difference between introduction.md vs the concept introduction.md?

The concept's introduction.md appears on the concept page for the exercise, while the exercise's introduction.md appears on the online editor before the instructions. Usually, they have the same content. The reason for 2 files is that for the some exercise's introduction.md we might want to tweak the concept's introduction a little bit. Or if an exercise teaches more than one concept, in the exercise's introduction.md we might want to "merge" the introduction.md of the concepts it teaches. But as a start, feel free to have the same content on both. This content must have all the information necessary for the student to solve the exercise, and. as much as possible it should avoid explaining things that won't be needed in the exercise.

You can read more about this in:

• Exercism Docs: Concepts
• Exercism Docs: Concept Exercises

What should be the package name for example solutions?

The same as the module name specified in go.mod and in the stubs/tests provided. This exemplar solution is used for the CI tests, which copies the file to the same folder as the tests before actually running them. If you are curious how this works:

https://github.com/exercism/go/blob/13f72b3e8091dd35eadc602b98c91587c53e4c20/bin/test-without-stubs#L51-L61

[MikaeelMF]

@andrerfcsantos Awesome! Then I will trim down unnecessary information for exercise's introduction.

[MikaeelMF]

So I thought this is possible, but is exercise solutions limited only to one file? or something is wrong with my config file?

update: After running reading https://github.com/exercism/go/blob/13f72b3e8091dd35eadc602b98c91587c53e4c20/bin/test-without-stubs#L51-L61 and the errors I think the answer is clear... 😅.

So based on this, I think it is probably better to split the exercises and concepts into two, one for http.server and the other for http.client. If it is ok with you, I will split them and change things up accordingly.

[MikaeelMF]

So this is interesting! I thought maybe Github does not allow for opening ports and running a server but the windows tests have passed, but ubuntu and macOS failed. My own system is a macOS and all tests run just fine. I don't understand what can cause this issue here.

Btw, I have split the main concept into two considering the limitation on having two files as answers, and reorganized files for them. I would really appreciate it if you could check them out and let me know if they are ok or not.

[junedev]

@MikaeelMF Regarding the tests: Could this be a timing issue? I had something like this before where it turned out it take a bit for the server to start so if you send requests to early it does not work. These kinds of issues often show up on CI runners as they are usually slower than the local machines people have.

In theory, having multiple solution files is definitely possible because there are languages where you have always more than one file, e.g. the code and the header file in C++. You can see an example of how this can be configured here: https://github.com/exercism/cpp/blob/main/exercises/concept/strings/.meta/config.json However, as André showed with that code snippet, our tooling might not be able to properly process this scenario currently. Mainly that means we need to fix the tooling though. What I haven't fully understood yet is why you think you need two files. The separate exercises seem very small currently. (Sidenote: Teaching two concepts with one exercise is not a problem.)

[MikaeelMF]

@junedev Thanks for the recommendation. I will put a pause after server creation to see if it solves the issue.

In the c++ example, I believe since .h and .cpp files are related and one is basically a structure for the other (as far as I understand c++) it does not encounter an issue. I believe it is better to divide writing a client and a server separately, because it is more than likely that one is tasked to build a server or a client separately rather than writing a client and server in a single file. Also, it can help learners to focus only on a single problem at a time, rather than being concerned with implementing and debugging basically two different concepts. Although it might make things a bit difficult for future improvements of these concepts and exercises, I think this method will help learners to get started with things a bit easier, that is why I did it this way.

[MikaeelMF]

Seems the timing issue was the case, but I need to check if the port is used or not!

[MikaeelMF]

Hi! I was wondering if anything is needed to change to merge this concept.

[junedev]

@MikaeelMF I was about to ask whether you want a full review now or not, I wasn't sure about the status. I have some time in the next days and will do the review then.

[MikaeelMF]

Awesome! Looking forward to it.

[MikaeelMF]

@junedev Sorry for my late response. I will edit the mentioned files based on your feedback. Please let me know if any other files need to get changed.

[MikaeelMF]

I also had a look at the exercises now and left my thoughts there as mentioned earlier.

As you can guess from the comments, there is still some work to be done here but you are on a good track. As we might have said before, if at any point you feel like you don't want to continue working on this, we can always merge this with "wip" status and create follow up issues to tackle the rest. Just let us know.

If you can manage to finish these two sets, I would probably set this so it awards 100 rep + the rep from the authoring because it was a huge effort and much more than one standard exercise + concept.

Thank you for letting me know. To be honest, I love to keep keep working on this concept, but recently I have been really busy and even had problems getting access to the Internet. I understand it might be inconvenient to have a concept hanging this long, and I totally understand if you would like to merge it with "wip" status. But in both cases, I will work on it and try to complete it as soon as possible.

[junedev]

In that case, feel free to chip away at your own pace. Just wanted to inform you about that possibility with the wip merge.